cli-anything-lldb

name	cli-anything-lldb
description	Stateful LLDB debugging via LLDB Python API
version	1.0.0
command	cli-anything-lldb
install	pip install cli-anything-lldb
requires	["lldb (Python bindings)","click>=8.0","prompt-toolkit>=3.0"]
categories	["debugging","native","lldb"]

LLDB CLI Skill

Use this CLI to run structured LLDB debugging workflows with JSON output.

Capabilities

• Create debug target from executable path
• Launch process or attach by pid/name
• Manage breakpoints (set/list/delete/enable/disable)
• Inspect threads, frames, locals, and backtrace
• Evaluate expressions in current frame
• Read/find process memory
• Load core dumps
• Interactive REPL with persistent session state
• Formal stdio Debug Adapter Protocol server for AI/editor clients

Quick Commands

cli-anything-lldb --json target create --exe /path/to/exe
cli-anything-lldb --json process launch --arg foo --arg bar
cli-anything-lldb --json breakpoint set --function main
cli-anything-lldb --json breakpoint set --function PluginEntry --allow-pending
cli-anything-lldb --json process continue
cli-anything-lldb --json process interrupt
cli-anything-lldb --json thread backtrace --limit 20
cli-anything-lldb --json frame locals
cli-anything-lldb --json expr "myVar"
cli-anything-lldb --json memory read --address 0x1000 --size 64
cli-anything-lldb --json session close

Debug Adapter Protocol

Use the DAP entry point when an AI client needs a real debug adapter lifecycle instead of shelling out separate CLI commands:

cli-anything-lldb-dap
cli-anything-lldb-dap --profile /path/to/stop-rules.json

or:

cli-anything-lldb dap
cli-anything-lldb dap --profile /path/to/stop-rules.json

The DAP server speaks stdio Content-Length frames and must have exclusive stdout. Do not print logs to stdout around it. Supported requests include initialize, launch, attach, configurationDone, setBreakpoints, setFunctionBreakpoints, threads, stackTrace, scopes, variables, setVariable, evaluate, continue, pause, next, stepIn, stepOut, source, loadedSources, readMemory, modules, exceptionInfo, disassemble, and disconnect.

DAP variables can expose child references for structs/classes/arrays. Use setVariable only while stopped; LLDB may reject writes to optimized-out or read-only values.

For long-running GUI debuggees, DAP continue is non-blocking from the client's point of view: the adapter sends the response and continued event first, then waits for LLDB on a background thread. DAP pause uses LLDB async interrupt. If an agent needs to change breakpoints while the debuggee is running, the adapter interrupts first and waits for a stopped state before mutating LLDB breakpoints; if the target does not stop in time, retry after an explicit pause/stopped cycle.

For GUI apps that stop on debugger-internal startup or shader-JIT breakpoints, launch and attach accept the non-standard boolean argument autoContinueInternalBreakpoints. Enable it only when those internal stops are noise for the task; the adapter emits an output event before auto-continuing. For target-specific noise, prefer structured stop rules through inline stopRules or an external stopRuleProfile/--profile JSON file. Rules can match by reason, module, function, and/or regex, then either stop with clear cliAnythingStop.origin metadata or continue automatically. Use profiles for apps such as C4D so their NVIDIA shader-JIT/startup traps live outside the generic adapter.

DAP stopped events include body.cliAnythingStop.origin: manualPause for a client pause request, internalTrap for a matched internal rule, and debuggee for ordinary program stops. Existing cli-anything-lldb-dap processes do not hot-load new code or profile contents; restart the adapter and re-attach or re-launch before expecting new rules to apply.

Command Groups

target

cli-anything-lldb --json target create --exe /path/to/exe [--arch x86_64]
cli-anything-lldb --json target info

process

cli-anything-lldb --json process launch [--arg ARG ...] [--env KEY=VALUE ...] [--cwd DIR] [--stop-at-entry]
cli-anything-lldb --json process attach --pid 1234
cli-anything-lldb --json process attach --name myapp --wait-for
cli-anything-lldb --json process continue
cli-anything-lldb --json process interrupt
cli-anything-lldb --json process detach
cli-anything-lldb --json process info

breakpoint

cli-anything-lldb --json breakpoint set --function main
cli-anything-lldb --json breakpoint set --file main.c --line 42 --condition "i > 10"
cli-anything-lldb --json breakpoint set --function LateLoadedSymbol --allow-pending
cli-anything-lldb --json breakpoint list
cli-anything-lldb --json breakpoint delete --id 1
cli-anything-lldb --json breakpoint enable --id 1
cli-anything-lldb --json breakpoint disable --id 1

thread / frame / step

cli-anything-lldb --json thread list
cli-anything-lldb --json thread select --id 11111
cli-anything-lldb --json thread backtrace --limit 50
cli-anything-lldb --json frame select --index 0
cli-anything-lldb --json frame info
cli-anything-lldb --json frame locals
cli-anything-lldb --json step over
cli-anything-lldb --json step into
cli-anything-lldb --json step out

expr / memory / core

cli-anything-lldb --json expr "argc"
cli-anything-lldb --json memory read --address 0x1000 --size 128
cli-anything-lldb --json memory find "needle" --start 0x1000 --size 4096
cli-anything-lldb --json core load --path /path/to/core

Agent Usage Notes

• Prefer --json for all automated flows.
• Separate non-REPL invocations share a persistent session daemon by default.
• Use --session-file PATH or CLI_ANYTHING_LLDB_SESSION_FILE to pin an explicit session for a task.
• Run cli-anything-lldb --json session close when finished so attached processes detach and launched debuggees are cleaned up.
• Use REPL when a human-like interactive shell is more convenient, not because persistence requires it.
• Unresolved CLI breakpoints fail by default; pass --allow-pending only when a future module/symbol load is expected.
• DAP unresolved breakpoints use protocol semantics: verified: false until resolved.
• DAP continue is non-blocking for long-running GUI processes, and DAP pause uses async interrupt.
• DAP breakpoint changes during an active continue first interrupt and wait for a stopped state before mutating LLDB.
• Use DAP stop-rule profiles for app-specific internal traps; restart and re-attach/re-launch after profile changes.
• memory find uses a chunked scan capped at 1 MiB per call.
• Call target create before process or core commands.
• Expect structured errors: {"error": "...", "type": "..."}