git:20260508.546b267 to git:20260508.3a56241

---

name: hopper-debugger

---

# Hopper Debugger

Goal: use Hopper through `mcporter` as a queryable disassembler, then combine the result with local source, LLDB, logs, and focused repros.

## Quick Start

Validate the MCP server:

```bash

MCPORTER_LIST_TIMEOUT=15000 timeout 20 mcporter list hopper --brief

```

List open Hopper documents:

```bash

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

```

If no document is open, open the binary/framework in Hopper first:

```bash

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

```

Hopper may show a first-open/import dialog. Let the user click the confirmation button, then retry the MCP call. Avoid parallel Hopper MCP calls; the server can close the transport or crash Hopper while import is still settling.

## Apple Frameworks

Prefer already extracted dyld-cache framework binaries when present:

```bash

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

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

```

Open one at a time when debugging SwiftUI/AppKit boundary issues:

```bash

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

```

Verify access:

```bash

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

```

Document names can start as `Untitled`; retry after Hopper finishes importing. Use `current_document`, 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:

```bash

mcporter call hopper.search_procedures pattern='NSStatusBar' --output json

mcporter call hopper.search_name pattern='NSStatusBarButtonCell' --output json

mcporter call hopper.search_strings pattern='NSStatusItem' --output json

```

3. Inspect one small target at a time:

```bash

mcporter call hopper.procedure_info procedure='<symbol>' --output json

mcporter call hopper.procedure_assembly procedure='<symbol>' --output json

mcporter call hopper.procedure_pseudo_code procedure='<symbol>' --output json

mcporter call hopper.procedure_callers procedure='<symbol>' --output json

mcporter call hopper.procedure_callees procedure='<symbol>' --output json

mcporter call hopper.xrefs address=0x12345678 --output json

```

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:

```bash

mcporter call hopper.search_strings pattern='NSStatusItem_Private_ForSwiftUI' --output json

mcporter call hopper.search_procedures pattern='popUpStatusBarMenu' --output json

mcporter call hopper.search_procedures pattern='trackMouse' --output json

mcporter call hopper.search_name pattern='NSStatusBarButtonCell' --output json

mcporter call hopper.search_name pattern='NSStatusItem' --output json

```

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 `NSStatusItem_Private_ForSwiftUI`

Compare disassembly against runtime state:

```bash

pgrep -af "App.app/Contents/MacOS/App"

lldb /path/to/debug/Binary

```

For hardened signed apps, attach may fail without `get-task-allow`; launch the raw debug binary under LLDB when needed.

## 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 `list_documents` before deeper searches.

- If mcporter is wedged, inspect processes before killing anything:

```bash

pgrep -af 'mcporter|HopperMCPServer|Hopper Disassembler'

```

- Prefer restarting the mcporter daemon over broad process kills:

```bash

mcporter daemon stop

mcporter daemon start

```