How to use the Hopper Binary Debugger agent skill

What an agent skill is and what this one does

An agent skill is a folder with a SKILL.md file that gives an AI agent instructions for a specific task. The agent loads the skill when a request matches its description, so you do not have to explain the workflow each time.

This skill covers reverse-engineering support using Hopper. Once it is set up, the agent can search for procedures and strings in a document such as AppKit, pull pseudo-code for a single procedure, and combine that with your local source code, the LLDB debugger, logs and small test cases to explain or diagnose a bug.

• Searches procedures and strings in Apple frameworks and app binaries loaded into Hopper
• Reads pseudo-code for one procedure at a time and summarises the control flow
• Checks hypotheses with LLDB, logging or a repro before editing app code
• Notes known gotchas, such as the correct call syntax and how to read Hopper's license state

Install the hopper-debugger skill

Download the ZIP from the skill's page on this directory and unzip it. The skill folder contains agents/openai.yaml and SKILL.md. Put the folder in one of these locations:

• Personal: ~/.claude/skills/ so every project on your machine can use it
• Project only: .claude/skills/ inside the repository you are working in
• Claude apps: upload the ZIP under Settings → Capabilities → Skills

Install Hopper Disassembler and mcporter

The skill needs Hopper Disassembler 6.0 or later. Hopper 6.0 and newer ship their own MCP server, called HopperMCPServer, inside the app bundle, so you do not need a third-party server. The skill also needs the mcporter command-line tool, which the source refers to but does not describe installing, so check its documentation for setup.

Then register Hopper's built-in server with mcporter. The --scope home flag is required. Without it, mcporter writes config/mcporter.json into whatever repository you are in.

Verify the connection and open a binary

Run the list command to confirm mcporter can reach Hopper. Then open a binary with Hopper. Small binaries import with no dialog; large frameworks can take minutes, so poll for the document rather than sleeping for a fixed time.

• Document names come from list_documents and have no .hop extension. A window titled AppKit.hop is called AppKit.
• The server does not fall back to the current document, so pass document on every document-scoped call.

Always use --args, never --params

This is the detail most likely to cost you time. mcporter accepts an unknown --params flag silently, drops the payload, and sends the call with no arguments. Hopper then returns "Document not found.", which looks like a licensing or document problem but is actually a syntax error.

Query a procedure by symbol or address

Start from the symbol you are trying to explain, search for it, then inspect one small target at a time. The procedure argument accepts either a symbol name or a hex address. Ask the agent to summarise the relevant control flow rather than pasting large decompilations.

• Other tools in the server include list_documents, current_document, set_current_document, list_segments, list_procedures, list_strings, search_strings, procedure_info, procedure_address and current_procedure.
• Hopper disassembly shows which store a value is written to; check the runtime to confirm it actually gets there.

Troubleshoot common failures

Most failures fall into a few patterns. The skill's guidance is to wrap Hopper calls in timeout, avoid sending concurrent requests while an import is running, and restart the mcporter daemon rather than killing processes broadly.

• "Connection closed": Hopper is probably not running or is showing a modal. Check the windows, dismiss the dialog, then retry.
• "Document not found.": almost always a missing --args flag, not a broken document.
• Wedged mcporter: stop and restart its daemon.