DAP Debugger

Kimchi ships with built-in Debug Adapter Protocol (DAP) support, giving the agent runtime debugger access. The DAP extension loads by default — no configuration required. It detects installed debug adapters on your PATH and registers debug tools the agent can use to set breakpoints, step through code, inspect variables, and evaluate expressions.

Supported languages

Language	Adapter	Transport	Install
TypeScript / JavaScript	`js-debug`	TCP	Download `js-debug-dap-<ver>.tar.gz` from vscode-js-debug releases, extract, and set `JS_DEBUG_PATH` to the extracted `js-debug/src/dapDebugServer.js`
Python	`debugpy`	stdio	`pip install debugpy`
Go	`dlv`	TCP	`go install github.com/go-delve/delve/cmd/dlv@latest`
C / C++ / Rust / Swift	`lldb-dap`	stdio	Install via your LLVM/Clang distribution or `cargo install lldb-dap`
Java / Kotlin	`java-debug`	stdio	Install the Java Debug Server
Ruby	`rdbg`	stdio	Ships with Ruby 3.1+ or: `gem install debug`
PHP	`php-debug-adapter`	stdio	`npm install -g php-debug-adapter`

Adapters are auto-detected via which on PATH (or module-presence checks for debugpy and js-debug). If an adapter binary is not found, the corresponding tools are silently unavailable and the status bar shows the adapter as not installed.

Project detection

Adapters are only activated when the current project has a matching root marker file:

Adapter	Root markers
`dlv`	`go.mod`
`js-debug`	`package.json`, `tsconfig.json`
`debugpy`	`pyproject.toml`, `setup.py`, `requirements.txt`, `Pipfile`
`lldb-dap`	`Cargo.toml`, `CMakeLists.txt`, `Makefile`, `Package.swift`
`java-debug`	`pom.xml`, `build.gradle`, `build.gradle.kts`
`rdbg`	`Gemfile`, `Rakefile`
`php-debug-adapter`	`composer.json`

Kimchi walks from the working directory up to the filesystem root looking for these markers. A Go project won't activate js-debug even if it's installed, and vice versa.

Tools

The DAP extension registers two layers of tools.

Composed tools (one-call)

These handle the full launch → breakpoint → inspect → terminate lifecycle in a single call. Prefer these for most debugging tasks.

Tool	Description
`debug_state_at`	Set a breakpoint at file:line, run to it, and return locals + backtrace + evaluated expressions
`debug_last_error`	Run until an exception is thrown, return the exception type/message + locals at the throw site
`debug_trace_calls`	Run to completion, return structured call records via sentinel parsing
`debug_watch_change`	Watch an expression for value changes across stepping

Primitive tools (interactive)

For fine-grained control over a debug session. Each tool takes a session_id returned by debug_launch.

Tool	Description
`debug_launch`	Launch a debug session (program, adapter, stop_on_entry)
`debug_set_breakpoint`	Set a breakpoint at file:line (with optional condition)
`debug_continue`	Resume execution, wait for next stop
`debug_locals`	Get local variables (with one level of nested struct expansion)
`debug_eval`	Evaluate an expression in the current frame
`debug_backtrace`	Get the call stack
`debug_terminate`	End the debug session
`step_in` / `step_over` / `step_out`	Step through code
`debug_set_variable`	Set a variable's value at runtime
`debug_restart`	Restart the debug session (if the adapter supports it)

The agent is prompted to prefer composed tools over manual stepping — for example, debug_state_at over a manual launch → breakpoint → continue → inspect sequence.

Plan mode

All debug tools are available in plan mode (explore/plan phases). Debugging is treated as investigation — launching and stopping a debuggee does not modify project files. Note that a launched debuggee executes arbitrary code and debug_set_variable mutates runtime memory, so plan mode is not strictly read-only while debug tools are enabled.

Language-specific skills

Language-specific debugging skills are injected into the system prompt on demand. They start inactive and activate on the first debug_* or step_* tool call, keeping the prompt compact when the agent is not debugging.

Each skill provides concrete expression syntax, data structure inspection patterns, and adapter-specific guidance for the language. For example, the Go skill documents that len(slice) works in debug_eval but method calls like cache.lru.Len() do not.

Status bar

The status bar reflects the three adapter states:

DAP: dlv, js-debug

When the project has markers for an adapter but the binary isn't installed, the missing adapter is called out:

DAP: dlv, js-debug · debugpy not installed

If every relevant adapter is missing:

DAP: dlv not installed

A one-time warning notification is shown on the first agent turn when adapters are missing.

Prerequisites

The DAP extension requires debug adapter binaries to be installed and available on your PATH. Install them with the commands listed in the Supported languages table above.

To verify an adapter is available:

which dlv
which lldb-dap
python3 -c "import debugpy"

For js-debug, set the JS_DEBUG_PATH environment variable to the path of dapDebugServer.js, or install it in node_modules:

# Option 1: Set the environment variable
export JS_DEBUG_PATH=/path/to/js-debug/src/dapDebugServer.js

# Option 2: Install in node_modules
npm install js-debug-adapter

If no adapters are found, the debug tools are not registered and the extension has no effect.