Debugging

When to reach for it

Use debug when reading the code isn’t enough and you need state from a running process: what does this variable look like after three iterations, which thread is stuck on which mutex, why does this branch fire under one input and not another. For static questions about the code itself, prefer code intelligence.

The debug.enabled gate

The debug tool is gated behind the debug.enabled setting, which is on by default. Turn it off in ~/.omp/agent/config.yml when you don’t want a run spawning debuggers:

# ~/.omp/agent/config.yml
debug:
  enabled: false

See the Settings page for the full config layout.

Adapters

omp auto-discovers DAP adapters on PATH and picks one from the target’s file extension and workspace markers (Cargo.toml, go.mod, pyproject.toml, package.json, …). Override with adapter when both a generic and a specialized backend are installed.

Additional adapters in the defaults table cover .NET (netcoredbg), Kotlin, Ruby (rdbg), PHP (Xdebug), Bash, Dart/Flutter, and Elixir. Install the one for your language; the tool reports a clear error when the adapter isn’t on PATH.

Actions

| Op | Use | | ---------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------- | | Lifecycle | | launch | Start a new process under the adapter (program, args, cwd ). | | attach | Attach to a running pid, or to a remote host+port. | | terminate | End the active session and clean up. | | sessions | List tracked sessions with adapter, state, and stop location. | | Breakpoints | | set_breakpoint | At file+line or function; optional condition / hit_condition. | | remove_breakpoint | Drop a source breakpoint. | | set_data_breakpoint | Watchpoint on a resolved variable (read/write/readWrite). | | set_instruction_breakpoint | Address-level breakpoint at instruction_reference. | | Execution | | continue | Resume the stopped thread. | | step_over | Step one source line, skipping calls. | | step_in | Step into the next call. | | step_out | Run to the caller’s return. | | pause | Interrupt a running target. | | Inspection | | threads | Every thread known to the adapter. | | stack_trace | Frames for the stopped thread, bounded by levels. | | scopes | Locals, arguments, registers for a frame_id. | | variables | Expand a scope_id or variable_ref. | | evaluate | Run expression. | in a frame; context selects watch / repl / hover. | | output | Drain buffered stdout/stderr from the target. |

Memory and disassembly ops (read_memory, write_memory, disassemble) and a custom_request escape hatch are available when the adapter supports them.

Worked example: catch a value after three iterations

A Python loop in etl/transform.py produces a wrong total only on the third pass. Set a conditional breakpoint, let it trip, then inspect locals before continuing.

# 1. Launch the script under debugpy.
debug action=launch adapter=debugpy program=etl/transform.py
 
# 2. Break inside the loop the third time through.
debug action=set_breakpoint file=etl/transform.py line=58 condition="i == 3"
debug action=continue
 
# 3. When it stops, read the frame.
debug action=stack_trace levels=5
debug action=scopes frame_id=0
debug action=variables scope_id=<locals_ref_from_scopes>
 
# 4. Ask the running interpreter a question.
debug action=evaluate frame_id=0 expression="sum(running_totals)" context=repl
 
# 5. Done.
debug action=continue
debug action=terminate

The repl-context evaluate is the escape hatch for raw debugger commands the DAP surface doesn’t expose directly. One active debug session per agent — call terminate before launching or attaching again.\n