{"id":51110319,"url":"https://github.com/alexmx/llmdb","last_synced_at":"2026-06-24T17:01:11.779Z","repository":{"id":365794866,"uuid":"1271683417","full_name":"alexmx/llmdb","owner":"alexmx","description":"Debug any Mac or iOS Simulator app from your terminal or your AI agent.","archived":false,"fork":false,"pushed_at":"2026-06-18T22:59:40.000Z","size":176,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-19T00:17:21.363Z","etag":null,"topics":["ai-agents","automation","cli","lldb","macos","mcp"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alexmx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-16T23:08:03.000Z","updated_at":"2026-06-18T22:59:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/alexmx/llmdb","commit_stats":null,"previous_names":["alexmx/llmdb"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/alexmx/llmdb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexmx%2Fllmdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexmx%2Fllmdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexmx%2Fllmdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexmx%2Fllmdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexmx","download_url":"https://codeload.github.com/alexmx/llmdb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexmx%2Fllmdb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34741320,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-24T02:00:07.484Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","automation","cli","lldb","macos","mcp"],"created_at":"2026-06-24T17:01:10.562Z","updated_at":"2026-06-24T17:01:11.770Z","avatar_url":"https://github.com/alexmx.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# llmdb\n\n\u003e Debug any Mac or iOS Simulator app from your terminal or your AI agent.\n\nWraps `lldb-dap` (Apple's Debug Adapter Protocol shim over LLDB) and gives AI agents a structured, session-oriented debugger. Launch a binary, set a breakpoint, step through code, inspect locals, evaluate expressions — all returning JSON, all driven by the same 17 verbs from the command line or over MCP.\n\n## See it in action\n\nA complete debug session — launch, break, continue, inspect, evaluate, step — in seven calls. Run it yourself against the bundled Swift fixture (`swift build` first).\n\n### 1. Launch — start the binary under the debugger\n\n```bash\nllmdb launch ./.build/debug/llmdb-fixture quick\n{\n  \"sessionId\" : \"2649sk\",\n  \"state\" : \"stopped\",\n  \"stopReason\" : { \"reason\" : \"exception\", \"description\" : \"signal SIGSTOP\", ... }\n}\n```\n\nThe daemon auto-spawns on first call. The binary stops on entry so the next call has a quiescent target.\n\n### 2. Set a breakpoint and run until it hits — one call\n\n```bash\nllmdb run-until ./Sources/Fixture/main.swift:35\n{\n  \"breakpoint\" : { \"id\" : 1, \"line\" : 35, \"verified\" : true, ... },\n  \"snapshot\"   : {\n    \"state\" : \"stopped\",\n    \"stopReason\" : { \"reason\" : \"breakpoint\", \"hitBreakpointIDs\" : [1], ... }\n  }\n}\n```\n\n`run-until` composes `break set` + `continue` for the most common agent flow. Use the two separately when you want to inspect between. For interactive UI apps where the user might take any amount of time to trigger the breakpoint, pass `--wait none` to fire and return immediately, then call `llmdb wait` to block until the stop arrives.\n\n### 3. Inspect — backtrace and typed locals\n\n```bash\nllmdb bt --depth 3\n{ \"frames\" : [\n    { \"name\" : \"compute(x:y:)\", \"line\" : 35, \"source\" : \".../main.swift\", ... },\n    { \"name\" : \"llmdb_fixture_main\", \"line\" : 63, ... },\n    { \"name\" : \"start\", \"source\" : \"/usr/lib/dyld`start\", ... }\n]}\n```\n\n```bash\nllmdb locals\n{ \"locals\" : [\n    { \"name\" : \"x\",       \"type\" : \"Int\", \"value\" : \"3\"  },\n    { \"name\" : \"y\",       \"type\" : \"Int\", \"value\" : \"4\"  },\n    { \"name\" : \"sum\",     \"type\" : \"Int\", \"value\" : \"7\"  },\n    { \"name\" : \"product\", \"type\" : \"Int\", \"value\" : \"12\" },\n    { \"name\" : \"diff\",    \"type\" : \"Int\", \"value\" : \"1\"  },\n    { \"name\" : \"total\",   \"type\" : \"Int\", \"value\" : \"20\" }\n]}\n```\n\nValues are lldb-formatted strings — agents can read them directly without parsing memory layouts.\n\n### 4. Evaluate — ask lldb anything\n\n```bash\nllmdb expr \"sum + diff\"\n{ \"type\" : \"Int\", \"value\" : \"8\", \"variablesReference\" : 0 }\n```\n\n`expr` runs in the context of the current frame. Use it when `locals` isn't enough — for property access (`self.state.count`), method calls, or arithmetic over locals.\n\n### 5. Step — and verify you moved\n\n```bash\nllmdb step --over\n{ \"state\" : \"stopped\", \"stopReason\" : { \"reason\" : \"step\", \"description\" : \"step over\", ... } }\n```\n\n```bash\nllmdb bt --depth 1\n{ \"frames\" : [{ \"name\" : \"llmdb_fixture_main\", \"line\" : 62, ... }] }\n```\n\n`--over` / `--in` / `--out` are mutually exclusive flags; default is `--over`.\n\n### 6. Tear down\n\n```bash\nllmdb stop\n{ \"ok\" : true }\n```\n\n## Install\n\n### Homebrew\n\n```bash\nbrew install alexmx/tools/llmdb\n```\n\n### Mise\n\n```bash\nmise use --global github:alexmx/llmdb\n```\n\n## Requirements\n\n- macOS 15 or later\n- Xcode or Command Line Tools (provides `lldb-dap`)\n- A debuggable target — debug builds with `get-task-allow=true` (the Xcode default). Release builds with Hardened Runtime can't be attached without re-signing.\n\nRun `llmdb doctor` to verify the toolchain and the daemon socket:\n\n```bash\nllmdb doctor\n{ \"checks\" : [\n    { \"name\" : \"lldb-dap\",   \"ok\" : true, \"detail\" : \"/Applications/Xcode.app/.../lldb-dap\" },\n    { \"name\" : \"socket-dir\", \"ok\" : true, \"detail\" : \"~/Library/Caches/llmdb\" },\n    { \"name\" : \"daemon\",     \"ok\" : true, \"detail\" : \"~/Library/Caches/llmdb/llmdbd.sock\" }\n]}\n```\n\nExits non-zero on any failure so it fits in shell scripts.\n\n## More examples\n\n```bash\n# Attach to a running process by PID\nllmdb attach --pid 12345\n\n# Attach to a SwiftUI app in the booted iOS Simulator\nllmdb attach --app com.example.MyApp\n\n# List all sessions across all agents talking to this daemon\nllmdb sessions\n\n# Manage breakpoints\nllmdb break set ./Sources/Fixture/main.swift:34\nllmdb break set ./Sources/Fixture/main.swift:49 --condition \"index == 2\"\nllmdb break list\nllmdb break delete 1\n\n# Pause a running session\nllmdb interrupt\n\n# Inspect threads\nllmdb threads\n```\n\n## Command reference\n\nAll commands return JSON by default (`--format json`). Pass `--session \u003cid\u003e` when more than one session is active.\n\n### Lifecycle\n\n| Command | Description | Key options |\n|---|---|---|\n| `launch \u003cbinary\u003e [-- args…]` | Launch a binary or `.app` bundle under `lldb-dap`. Stops on entry. | `.app` bundles (or paths inside one) route via LaunchServices so the app registers with AppKit — needed for accessibility / UI-automation tools to see the process |\n| `attach` | Attach to a running process or Simulator app | `--pid N` OR `--app \u003cbundle-id\u003e` (exactly one) |\n| `stop` | Detach / terminate the session | `--session ID` |\n| `sessions` | List active debug sessions | — |\n\n### Breakpoints\n\n| Command | Description | Key options |\n|---|---|---|\n| `break set \u003cfile\u003e:\u003cline\u003e` | Set a source breakpoint; returns the verified BP and a session snapshot | `--condition \u003cexpr\u003e`, `--hit-condition \u003cexpr\u003e` |\n| `break list` | List breakpoints in the session | — |\n| `break delete \u003cid\u003e` | Remove a breakpoint by id; returns the survivors | — |\n\n### Execution\n\nAll four blocking verbs accept `--wait \u003cseconds|none\u003e`. Default timeouts: `continue` 60s, `step` 30s, `interrupt` 10s, `run-until` 60s. `--wait none` (or `--wait 0`) is fire-and-forget — the target starts running and the call returns immediately; pair with `wait` to block later.\n\n| Command | Description | Key options |\n|---|---|---|\n| `continue` | Resume until the next stop | `--wait \u003cseconds\\|none\u003e` |\n| `run-until \u003cfile\u003e:\u003cline\u003e` | `break set` + `continue` in one call | `--wait \u003cseconds\\|none\u003e` |\n| `step` | Step one source line | `--over` (default), `--in`, `--out`; `--wait` |\n| `interrupt` | Pause a running session | `--wait \u003cseconds\\|none\u003e` |\n| `wait` | Block until the session leaves `running` | `--timeout \u003cseconds\u003e` (default 60) |\n\n### Inspection\n\n| Command | Description | Key options |\n|---|---|---|\n| `bt` | Structured backtrace for the stopped thread | `--thread N`, `--depth N` |\n| `locals` | Typed locals for a stack frame | `--frame N` (default 0) |\n| `threads` | List threads in the session | — |\n| `expr \u003cexpression\u003e` | Evaluate in the context of a frame | `--frame N` |\n\n### System\n\n| Command | Description | Key options |\n|---|---|---|\n| `doctor` | Verify lldb-dap, socket dir, daemon reachability. `daemon: ok+idle` on a fresh machine; only an unreachable stale socket counts as a failure. Exits 1 on any failure. | — |\n| `daemon` | Run `llmdbd` (normally auto-spawned). | `--socket PATH` to override |\n| `mcp` | Start the stdio MCP server. | `--setup` prints client config snippets |\n\n## MCP server\n\nllmdb runs as a stdio MCP server. Every CLI verb is exposed as an `llmdb_*` tool (`llmdb_launch`, `llmdb_break_set`, `llmdb_run_until`, …) mirroring the CLI 1:1.\n\n```bash\nllmdb mcp --setup   # prints config for Claude Code, Cursor, Codex CLI, etc.\n```\n\nManual configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"llmdb\": { \"command\": \"llmdb\", \"args\": [\"mcp\"] }\n  }\n}\n```\n\n### Multi-agent isolation\n\nTwo agents driving llmdb at the same time share a single daemon by default — convenient, but they see each other's sessions and the \"default session when only one is active\" shortcut stops working. Give each agent its own daemon via the `LLMDB_SOCKET_PATH` env var:\n\n```json\n{\n  \"mcpServers\": {\n    \"llmdb\": {\n      \"command\": \"llmdb\",\n      \"args\": [\"mcp\"],\n      \"env\": { \"LLMDB_SOCKET_PATH\": \"/tmp/llmdb-agent-a.sock\" }\n    }\n  }\n}\n```\n\nSet a distinct path per agent — auto-spawn picks up the override automatically and each agent gets a fully isolated daemon, sessions, and `lldb-dap` children.\n\n## License\n\nReleased under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexmx%2Fllmdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexmx%2Fllmdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexmx%2Fllmdb/lists"}