hopper-debugger

---
name: hopper-debugger
description: "Use when working with hopper debugging: macOS/iOS binaries, ObjC/Swift symbols, dyld, LLDB from steipete/agent-scripts."
source: https://github.com/steipete/agent-scripts/tree/main/skills/hopper-debugger
generated: 2026-05-27T20:55:50.122Z
category: tool
audience: engineers
---

## When to use

- Using the hopper-debugger skill's upstream workflow, guardrails, and local-tool assumptions.
- Auditing commands or operational steps before changing hopper debugger behavior.
- Needing a compact agent reference for hopper debugging: macOS/iOS binaries, ObjC/Swift symbols, dyld, LLDB.

## Key concepts

### Apple Frameworks

Prefer already extracted dyld-cache framework binaries when present: Open one at a time when debugging SwiftUI/AppKit boundary issues: Verify access: Document names can start as Untitled; retry after Hopper finishes importing. Use currentdocument, symbol/string searches, and window title changes to identify AppKit vs SwiftUI.

### Query Workflow

1. Start from the local source path or runtime symbol you are trying to explain. 2. Search names/procedures/strings: 3. Inspect one small target at a time: 4. Summarize the relevant control flow; do not paste large decompilations. 5. Validate the hypothesis with LLDB/logging/repro before editing app code.

### Status Item / Menu Click Bugs

Useful AppKit/SwiftUI searches: Symbols worth inspecting when menu bar clicks do nothing: -[NSStatusBarButtonCell trackMouse:inRect:ofView:untilMouseUp:] -[NSStatusBarButtonCell sendActionFrom:] -[NSStatusItem popUpStatusBarMenu:] -[NSApplication sendAction:to:from:] SwiftUI status/menu symbols that reference NSStatusItemPrivateForSwiftUI Compare disassembly against runtime state: For hardened signed apps, attach may fail without get-task-allow; launch the raw debug binary under LLDB when...

### Failure Handling

Wrap Hopper calls with timeout; a modal/import or closed document can leave the transport stuck. Do not send concurrent Hopper MCP requests during import. If a query is expensive, wait for it to finish before starting another. If calls report Connection closed, check for a Hopper modal, then retry after confirmation. If Hopper crashes, reopen a single document, wait for import/analysis, and re-run listdocuments before deeper searches. If mcporter is wedged, inspect processes before killing...

## API reference

```
npx skills add steipete/agent-scripts --skill hopper-debugger
```

Install the hopper-debugger skill from steipete/agent-scripts.

```
npx skills add steipete/agent-scripts --skill hopper-debugger
```

```
MCPORTERLISTTIMEOUT=15000 timeout 20 mcporter list hopper --brief.
```

Command or snippet documented by the upstream hopper-debugger skill.

```
MCPORTER_LIST_TIMEOUT=15000 timeout 20 mcporter list hopper --brief
```

```
MCPORTERCALLTIMEOUT=20000 timeout 30 mcporter call hopper.listdocuments --output json.
```

Command or snippet documented by the upstream hopper-debugger skill.

```
MCPORTER_CALL_TIMEOUT=20000 timeout 30 mcporter call hopper.list_documents --output json
```

```
open -a "Hopper Disassembler" /path/to/Binary.
```

Command or snippet documented by the upstream hopper-debugger skill.

```
open -a "Hopper Disassembler" /path/to/Binary
```

```
/tmp/dsc-appkit/System/Library/Frameworks/AppKit.framework/Versions/C/AppKit.
```

Command or snippet documented by the upstream hopper-debugger skill.

```
/tmp/dsc-appkit/System/Library/Frameworks/AppKit.framework/Versions/C/AppKit
/tmp/dsc-appkit/System/Library/Frameworks/SwiftUI.framework/Versions/A/SwiftUI
```

```
open -a "Hopper Disassembler" /tmp/dsc-appkit/System/Library/Frameworks/AppKit.framework/Versions/C/AppKit.
```

Command or snippet documented by the upstream hopper-debugger skill.

```
open -a "Hopper Disassembler" /tmp/dsc-appkit/System/Library/Frameworks/AppKit.framework/Versions/C/AppKit
mcporter call hopper.list_documents --output json

open -a "Hopper Disassembler" /tmp/dsc-appkit/System/Library/Frameworks/SwiftUI.framework/Versions/A/SwiftUI
mcporter call hopper.list_documents --output json
```

```
mcporter call hopper.listdocuments --output json.
```

Command or snippet documented by the upstream hopper-debugger skill.

```
mcporter call hopper.list_documents --output json
mcporter call hopper.current_document --output json
mcporter call hopper.search_strings pattern=SwiftUI --output json
mcporter call hopper.search_strings pattern=NSStatusItem --output json
```

## Gotchas

- Prefer already extracted dyld-cache framework binaries when present:.
- Do not send concurrent Hopper MCP requests during import. If a query is expensive, wait for it to finish before starting another.
- Prefer restarting the mcporter daemon over broad process kills:.

---
Generated by SkillMake from https://github.com/steipete/agent-scripts/tree/main/skills/hopper-debugger on 2026-05-27T20:55:50.122Z.
Verify against source before relying on details.

File: ~/.claude/skills/hopper-debugger/SKILL.md