Debugium DAP Debugger

Category: Development & Coding | Uploader: Algiras | Downloads: 0 | Version: v1.0（Latest）

Drive live debug sessions for Python, Node.js, TypeScript, C, C++, Rust, Java, Scala, and WebAssembly using the Debugium MCP tools. Use when asked to debug code, set breakpoints, inspect variables, step through execution, trace bugs, or find why something crashes.

Changelog: Source: GitHub https://github.com/Algiras/debugium

Directory Structure

Current level: Root

📁 .claude-plugin/
- 📄 marketplace.json 1011 B
- 📄 plugin.json 714 B
📁 .cursor/
- 📄 mcp.json 215 B
📁 .github/
- 📁 workflows/
  - 📄 ci.yml 1.9 KB
  - 📄 pages.yml 666 B
  - 📄 release.yml 4.4 KB
📁 crates/
- 📁 dap-types/
  - 📁 src/
    
    📄 lib.rs 9.4 KB
  - 📄 Cargo.toml 158 B
- 📁 debugium-server/
  - 📁 src/
    
    📁 dap/
    
    📄 adapter.rs 28.4 KB
    
    📄 client.rs 8.1 KB
    
    📄 mod.rs 50 B
    
    📄 session.rs 56.6 KB
    
    📁 mcp/
    
    📄 mod.rs 63.0 KB
    
    📄 tools.rs 104.5 KB
    
    📁 server/
    
    📄 hub.rs 3.1 KB
    
    📄 mod.rs 5.2 KB
    
    📄 routes.rs 19.5 KB
    
    📄 ctl.rs 15.6 KB
    
    📄 home.rs 2.9 KB
    
    📄 main.rs 20.0 KB
  - 📁 tests/
    
    📄 integration.rs 72.2 KB
  - 📄 Cargo.toml 895 B
- 📁 debugium-ui/
  - 📁 dist/
    
    📁 pkg/
    
    📄 cm_init.js 17.4 KB
    
    📄 debugium_ui.d.ts 4.7 KB
    
    📄 debugium_ui.js 46.4 KB
    
    📄 debugium_ui_bg.wasm 1.3 MB
    
    📄 debugium_ui_bg.wasm.d.ts 2.8 KB
    
    📄 package.json 261 B
    
    📄 index.html 1.2 KB
    
    📄 index.html.template 1.2 KB
    
    📄 style.css 50.8 KB
  - 📁 src/
    
    📄 editor.rs 2.0 KB
    
    📄 lib.rs 207.9 KB
  - 📄 Cargo.toml 776 B
  - 📄 index.html 1.0 KB
📁 dap_cli/
- 📁 static/
  - 📄 app.js 13.4 KB
  - 📄 index.html 4.6 KB
  - 📄 style.css 7.3 KB
- 📄 __init__.py 0 B
- 📄 cli.py 1.9 KB
- 📄 client.py 7.1 KB
- 📄 repl.py 6.1 KB
- 📄 session.py 3.8 KB
- 📄 web_server.py 3.7 KB
📁 docs/
- 📄 DAP_COVERAGE_AUDIT.md 8.2 KB
- 📄 index.html 30.8 KB
- 📄 screenshot.png 159.7 KB
- 📄 ui-protocol-coverage-audit.md 4.3 KB
📁 examples/
- 📄 c-cpp.dap.json 296 B
- 📄 java.dap.json 244 B
- 📄 node.dap.json 326 B
- 📄 python.dap.json 295 B
- 📄 README.md 2.8 KB
- 📄 remote-java.dap.json 417 B
- 📄 remote-python.dap.json 519 B
- 📄 rust.dap.json 239 B
- 📄 scala-jvm.dap.json 455 B
- 📄 typescript.dap.json 393 B
- 📄 wasm.dap.json 637 B
📁 npm/
- 📄 install.js 2.7 KB
- 📄 run.js 462 B
📁 scripts/
- 📄 sync-ui.sh 957 B
📁 skills/
- 📁 debugium/
  - 📄 SKILL.md 15.3 KB
📁 tests/
- 📁 buggy/
  - 📁 rust/
    
    📁 src/
    
    📄 main.rs 2.0 KB
    
    📄 Cargo.lock 153 B
    
    📄 Cargo.toml 77 B
  - 📄 cache.py 1.1 KB
  - 📄 demo.py 911 B
  - 📄 leak.ts 3.6 KB
  - 📄 main.py 2.8 KB
  - 📄 memo.js 3.4 KB
  - 📄 memo.ts 3.7 KB
  - 📄 package.json 21 B
  - 📄 scheduler.py 1.2 KB
  - 📄 transform.py 969 B
- 📁 target_rust/
  - 📁 src/
    
    📄 main.rs 2.6 KB
  - 📄 Cargo.lock 155 B
  - 📄 Cargo.toml 80 B
- 📄 target_c.c 1.3 KB
- 📄 target_cpp.cpp 1.7 KB
- 📄 target_node.js 1.5 KB
- 📄 target_python.py 1.9 KB
- 📄 target_rust.rs 746 B
- 📄 target_subprocess.py 662 B
- 📄 target_subprocess_child.py 313 B
- 📄 target_threads.py 544 B
- 📄 target_ts.ts 2.8 KB
- 📄 target_wasm.c 492 B
- 📄 TargetJava.java 1.1 KB
- 📄 TargetScala.scala 549 B
- 📄 test_cli.py 4.1 KB
- 📄 test_cli_js.py 4.8 KB
- 📄 trace_api.py 1.2 KB
- 📄 trace_js.py 1.2 KB
- 📄 trace_threads.py 1.3 KB
📁 tools/
- 📁 java-dap-adapter/
  - 📄 JavaDapAdapter.class 23.2 KB
  - 📄 JavaDapAdapter.java 32.5 KB
  - 📄 run.sh 308 B
📄 .env.example 51 B
📄 .gitignore 375 B
📄 .mcp.json 332 B
📄 .npmignore 9 B
📄 Cargo.lock 86.3 KB
📄 Cargo.toml 1.1 KB
📄 CHANGELOG.md 3.4 KB
📄 CLAUDE.md 10.1 KB
📄 dap.json.example 661 B
📄 dap.json.remote-example 532 B
📄 FUTURE_FEATURES.md 2.2 KB
📄 install.sh 3.4 KB
📄 package.json 844 B
📄 README.md 13.4 KB
📄 run_test.sh 106 B
📄 rust-toolchain.toml 92 B
📄 server.json 559 B
📄 SKILL.md 14.3 KB
📄 target.js 101 B
📄 test_target.py 138 B

SKILL.md

---
name: Debugium DAP Debugger
description: Drive live debug sessions for Python, Node.js, TypeScript, C, C++, Rust, Java, Scala, and WebAssembly using the Debugium MCP tools. Use when asked to debug code, set breakpoints, inspect variables, step through execution, trace bugs, or find why something crashes.
---

# Debugium Debugger Skill

Debugium is a DAP (Debug Adapter Protocol) client with an MCP interface and a real-time web UI. You can control any active debug session — set breakpoints, step through code, inspect live values, record findings, and annotate the source editor.

---

## Setup & Connection

### 1. Install

```bash
cargo install --path crates/debugium-server
```

### 2. Register MCP server

Add to `.mcp.json` (project root) or `~/.claude.json`:
```json
{
  "mcpServers": {
    "debugium": { "command": "debugium", "args": ["mcp"] }
  }
}
```

### 3. Install language prerequisites

| Language | Install |
|----------|---------|
| Python | `pip install debugpy` |
| Node.js / TypeScript | js-debug (build from microsoft/vscode-js-debug) + `npm i -g tsx` for TS |
| C / C++ / Rust | `lldb-dap` (ships with LLVM: `brew install llvm`) |
| Java | microsoft/java-debug adapter JAR |
| Scala | Running Metals language server with DAP |

### 4. Launch a debug session

**Preferred**: use a `dap.json` config from `examples/`. All paths must be absolute.

```bash
# Python — multiple breakpoints with -b
debugium launch /abs/path/script.py --config examples/python.dap.json \
  -b /abs/path/script.py:42 -b /abs/path/script.py:67

# Comma-separated lines in one file
debugium launch /abs/path/script.py --adapter python \
  --breakpoint /abs/path/script.py:10,15,20

# Node.js
debugium launch /abs/path/app.js --config examples/node.dap.json \
  -b /abs/path/app.js:15 -b /abs/path/app.js:30

# TypeScript
debugium launch /abs/path/app.ts --config examples/typescript.dap.json \
  -b /abs/path/app.ts:10

# C / C++ (compile with debug symbols first: cc -g -O0)
debugium launch /tmp/a.out --config examples/c-cpp.dap.json \
  -b /abs/path/main.c:20

# Rust (cargo build first)
debugium launch ./target/debug/myapp --config examples/c-cpp.dap.json \
  -b /abs/path/src/main.rs:10

# Remote attach (debugpy already listening on 127.0.0.1:5678)
python3 -m debugpy --listen 127.0.0.1:5678 --wait-for-client app.py &
debugium launch app.py --config examples/remote-python.dap.json \
  -b /abs/path/app.py:42
```

**Shorthand** (Python only): `debugium launch script.py --adapter python -b ...`

**Auto-discovery**: place `dap.json` in project root, then just `debugium launch program -b ...`

### 5. Verify connection

Call `get_sessions` — if empty, the server isn't running. Launch a session first.

---

## Web UI

The debugger launches a web UI automatically (unless `--no-open-browser`). Features:

- **Layout presets**: Slim (source only), Std (console collapsed), Full (everything open)
- **Light/Dark mode**: toggle with Ctrl/Cmd+D or the header button
- **Panels**: Source, Console, Variables, Stack, Breakpoints, Watch, Findings, Timeline
- **Icon toolbar**: Continue, Pause, Step In/Over/Out, Stop, Restart (F-key shortcuts)
- **AI activity**: LLM tool calls are shown in real-time via the console

---

## Debugging Workflow

### Standard loop

```
1. launch_session        – start a debug session (or get_sessions if one is already running)
2. get_debug_context     – orient: paused_at + locals + call_stack + source_window + breakpoints in ONE call
3. evaluate / get_variables  – inspect specific values
4. step_over / step_in   – advance (blocking: waits for pause, safe to chain)
5. get_debug_context     – re-orient after stepping
6. annotate / add_finding – record conclusions in the UI
7. Repeat 3–6 as needed
8. stop_session          – clean up when done
```

**Key insight**: `get_debug_context` replaces the old 7-call chain of
`get_threads → get_stack_trace → get_scopes → get_variables`. Use it first.

---

## Tool Reference

### Session

#### `launch_session`
Launch a new debug session autonomously — no human intervention needed. Spawns the adapter, sets breakpoints, waits until paused.
```json
{ "program": "/abs/path/script.py", "adapter": "python", "breakpoints": ["/abs/path/script.py:42"] }
```
Returns `{ "session_id": "...", "status": "paused" | "running" }`. Use the returned `session_id` for all subsequent tool calls.

#### `stop_session`
Stop and clean up a debug session. Sends disconnect, kills adapter, removes from registry.
```json
{ "session_id": "session-123" }
```

#### `get_sessions` / `list_sessions`
List active sessions. Empty = server not started.
```json
{}
```

---

### Source

#### `get_source`
Read a source file with optional line zoom.
```json
{ "path": "/abs/path/to/file.py", "around_line": 42, "context_lines": 10 }
```

---

### Breakpoints

#### `set_breakpoints`
Set breakpoints in a file (replaces all existing in that file).
```json
{ "file": "/abs/path/to/script.py", "lines": [42, 67, 103] }
```

#### `set_breakpoint`
Set or update a single breakpoint with an optional condition.
```json
{ "file": "/abs/path/to/script.py", "line": 42, "condition": "x > 10" }
```

#### `list_breakpoints` / `clear_breakpoints`
```json
{}
```

#### `set_function_breakpoints`
Break on a function name.
```json
{ "names": ["my_function", "ClassName.method"] }
```

#### `set_exception_breakpoints`
```json
{ "filter": "raised" }   // or "uncaught"
```

---

### Execution Control

#### `continue_execution`
Resume until the next breakpoint. Returns `console_line_count` — pass it to
`wait_for_output` as `from_line` to avoid matching stale output.
```json
{ "thread_id": 1 }
```
Returns: `{ "status": "running", "console_line_count": 42, "hint": "..." }`

#### `step_over` / `step_in` / `step_out`
**Blocking** — waits for the adapter to pause before returning. Safe to chain
back-to-back without sleeps. Returns confirmation + "Call get_debug_context for location."
```json
{ "thread_id": 1 }
```

#### `pause` / `restart` / `terminate` / `disconnect`
```json
{ "thread_id": 1 }
```

---

### Inspection (use when paused)

#### `get_debug_context` ★ START HERE
Single call returning: `paused_at`, `locals`, `call_stack`, `source_window (±5 lines)`,
`breakpoints`, `frame_id`, `thread_id`. Replaces the old get_threads→stack→scopes→vars chain.
```json
{}
```

#### `get_threads`
```json
{}
```

#### `get_stack_trace`
```json
{ "thread_id": 1, "depth": 20 }
```
Returns frames with `id` (frame_id), `name`, `line`, `source`.

#### `get_scopes`
```json
{ "frame_id": 2 }
```
Returns scopes (Locals, Globals) each with `variablesReference`.

#### `get_variables`
```json
{ "variables_reference": 6 }
```
Nested objects have their own `variablesReference` — call recursively to drill in.

#### `evaluate`
Evaluate any expression in the current frame.
```json
{ "expression": "len(my_list)", "frame_id": 2, "context": "repl" }
```

#### `set_variable`
Mutate a variable in the current scope.
```json
{ "variables_reference": 6, "name": "counter", "value": "0" }
```

#### `get_exception_info`
Details about the current exception (when stopped on exception).
```json
{}
```

#### `get_capabilities`
What the adapter supports.
```json
{}
```

---

### Console Output

#### `get_console_output`
Last N lines of stdout/stderr.
```json
{ "lines": 50 }
```

#### `wait_for_output`
Poll until stdout matches a regex (or timeout). Use `from_line` from
`continue_execution` to only match **new** output — not output from earlier in the session.
```json
{ "pattern": "Error.*line", "from_line": 42, "timeout_secs": 10 }
```

---

### History & Timeline

#### `get_timeline`
Every stop in this session: file, line, changed variables, stack summary.
```json
{ "limit": 50 }
```

#### `get_variable_history`
How one variable's value changed across all stops. Answers "when did X go wrong?"
```json
{ "name": "counter" }
```

---

### Annotations & Findings (record conclusions in the UI)

#### `annotate`
Pin a colored marker on a source line, visible to the human in the editor.
```json
{ "file": "/abs/path/to/file.py", "line": 42, "message": "off-by-one here", "color": "red" }
```

#### `get_annotations`
Read back all annotations you've already placed — do this at session start to avoid
re-investigating known lines.
```json
{}
```

#### `add_finding`
Record a structured conclusion in the Findings panel.
```json
{ "message": "counter overflows at iteration 256", "level": "error" }
```
Levels: `info`, `warning`, `error`.

#### `get_findings`
Read back all findings — do this at session start to avoid restating known conclusions.
```json
{}
```

---

### Watch Expressions

#### `add_watch` / `remove_watch`
Expressions evaluated automatically at every stop.
```json
{ "expression": "len(queue)" }
```

#### `get_watches`
Current expressions + their last evaluated values.
```json
{}
```

---

### Compound / LLM Tools

#### `step_until`
Step until an expression becomes true (up to max_steps).
```json
{ "condition": "i == 10", "max_steps": 50 }
```

#### `run_until_exception`
Continue until any exception is raised.
```json
{}
```

#### `compare_snapshots`
Diff variable snapshots between two timeline stops.
```json
{ "stop_a": 3, "stop_b": 7 }
```

#### `find_first_change`
Find the first timeline stop where a variable changed (optionally from an expected value).
```json
{ "variable_name": "counter", "expected_value": "0" }
```

#### `get_call_tree`
Stack + locals for each frame in one call.
```json
{ "max_depth": 5 }
```

#### `step_until_change`
Step until a variable's value changes.
```json
{ "variable_name": "status", "max_steps": 20 }
```

#### `explain_exception`
When stopped on an exception, gather all relevant context in one call.
```json
{}
```

#### `restart_frame`
Re-run execution from a specific stack frame (requires `supportsRestartFrame`).
```json
{ "frame_id": 2 }
```

---

### Navigation & Source Discovery

#### `goto_targets`
Get valid jump targets for a given source location (requires `supportsGotoTargetsRequest`).
```json
{ "file": "/abs/path/to/file.py", "line": 43 }
```

#### `goto`
Jump execution to a target without running intermediate code.
```json
{ "thread_id": 1, "target_id": 0 }
```

#### `breakpoint_locations`
Get valid breakpoint positions in a line range (requires `supportsBreakpointLocationsRequest`).
```json
{ "file": "/abs/path/to/file.js", "line": 30, "end_line": 40 }
```

#### `step_in_targets`
List possible step-in targets when a line has multiple calls (requires `supportsStepInTargetsRequest`).
```json
{ "frame_id": 0 }
```

#### `loaded_sources`
List all source files currently loaded by the adapter (requires `supportsLoadedSourcesRequest`).
```json
{}
```

#### `source_by_reference`
Fetch source code for generated/internal code by sourceReference ID.
```json
{ "source_reference": 2017626721 }
```

---

### Mutation

#### `set_expression`
Set the value of an expression (requires `supportsSetExpression`).
```json
{ "expression": "obj.field", "value": "42", "frame_id": 0 }
```

---

### Memory & Disassembly (native debugging)

#### `read_memory`
Read raw bytes from debuggee memory (requires `supportsReadMemoryRequest`).
```json
{ "memory_reference": "0x7fff5000", "count": 128 }
```

#### `write_memory`
Write raw bytes to debuggee memory (requires `supportsWriteMemoryRequest`).
```json
{ "memory_reference": "0x7fff5000", "data": "AQIDBA==" }
```

#### `disassemble`
Disassemble machine instructions (requires `supportsDisassembleRequest`).
```json
{ "memory_reference": "0x100003f00", "instruction_count": 20 }
```

---

### Control

#### `cancel_request`
Cancel an in-flight request (requires `supportsCancelRequest`).
```json
{ "request_id": 42 }
```

---

### Data Breakpoints (watchpoints)

#### `set_data_breakpoint`
Break when a variable is written/read.
```json
{ "name": "counter", "access_type": "write" }
```

#### `list_data_breakpoints` / `clear_data_breakpoints`
```json
{}
```

---

### Session Persistence

#### `export_session`
Export breakpoints, annotations, findings, and watches as a JSON bundle.
```json
{}
```

#### `import_session`
Restore exported state into the current session.
```json
{ "data": { "..." } }
```

---

## Supported Adapters

| Language     | `--adapter` flag              | Prerequisite                          | Verified |
|-------------|-------------------------------|---------------------------------------|----------|
| Python      | `python` / `debugpy`          | `pip install debugpy`                 | ✅ |
| Node.js     | `node` / `js`                 | js-debug (bundled)                    | ✅ |
| TypeScript  | `typescript` / `ts` / `tsx`   | js-debug + `tsx` or `ts-node`         | ✅ |
| C / C++     | `lldb` / `codelldb`           | `lldb-dap`                            | ✅ |
| Rust        | `lldb` / `rust`               | `lldb-dap` + `cargo build`            | ✅ |
| Java        | `java` / `jvm`                | microsoft/java-debug adapter JAR      | ✅ |
| Scala       | `--config scala-jvm.dap.json` | `scalac` + Scala library JAR          | ✅ |
| WebAssembly | `--config wasm.dap.json`      | `wasmtime` + `lldb-dap` (LLVM ≥16)   | ✅ |
| Any adapter | `--config dap.json`           | See `dap.json.example`                | ✅ |

Remote attach is supported via `dap.json` with `host` + `port` fields (no local adapter needed).

---

## CLI Breakpoint Syntax

```bash
# Repeated -b flags (short for --breakpoint)
debugium launch app.py --adapter python -b app.py:10 -b app.py:20 -b other.py:5

# Comma-separated lines in one file
debugium launch app.py --adapter python --breakpoint app.py:10,15,20

# Mix both
debugium launch app.py --adapter python -b app.py:10,20 -b other.py:5
```

---

## Tips

1. **Start with `get_debug_context`** — not `get_source`. Live runtime values beat static reading.
2. **Steps are blocking** — chain `step_over` calls freely; each confirms the pause before returning.
3. **Thread `console_line_count`** — pass it from `continue_execution` into `wait_for_output` as `from_line` to avoid false positives on old output.
4. **Read before re-investigating** — call `get_annotations` and `get_findings` at the start of each session to see what you already know.
5. **Use `evaluate` before stepping** — cheaper than advancing line-by-line. Narrow the bug first.
6. **Use `step_until`** — instead of manually looping, let the tool advance until your condition fires.
7. **Drill nested variables** — any `variablesReference > 0` has children; call `get_variables` recursively.
8. **Set all breakpoints at once** — one `set_breakpoints` call beats many individual ones.

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

Debugium DAP Debugger

Directory Structure

SKILL.md

Report

Notice