{
  "markdown": "# Debugium\n\n**A multi-language debugger with a real-time web UI and LLM integration via MCP.**\n\nDebug Python, JavaScript, TypeScript, C, C++, Rust, Java, Scala, and WebAssembly programs from your browser — with AI-driven analysis through the [Model Context Protocol](https://modelcontextprotocol.io/).\n\n[![CI](https://github.com/Algiras/debugium/actions/workflows/ci.yml/badge.svg)](https://github.com/Algiras/debugium/actions/workflows/ci.yml)\n[![Docs](https://img.shields.io/badge/docs-algiras.github.io%2Fdebugium-blue)](https://algiras.github.io/debugium)\n\n![Debugium UI — paused at a breakpoint in target_python.py with variables, call stack, breakpoints, watch, timeline, and console panels](docs/screenshot.png)\n\n---\n\n## Features\n\n### Web UI\n- **Real-time web UI** — source viewer, breakpoints, variables (recursive expansion), call stack, console, timeline, watch expressions, findings — all updated live via WebSocket\n- **Multi-tab source viewer** — open multiple files, click stack frames to navigate\n- **Variable search** — filter variables by name with recursive expansion\n- **Changed-variable highlighting** — variables that changed since last stop shown in orange\n- **Thread selector** — switch between threads in multi-threaded programs\n- **Panel collapse & resize** — drag to resize, toggle to collapse; Slim / Standard / Full layout presets\n- **Dark / light mode** toggle\n- **Auto-reconnect** — UI reconnects after a dropped WebSocket, with visual status indicator\n- **Keyboard shortcuts** — F5 continue, F10 step over, F11 step in, Shift+F11 step out, Ctrl/Cmd+D dark mode\n- **Button animations** — in-flight spinner and completion flash for debug commands\n\n### Debugging\n- **Multi-language** — Python (debugpy), Node.js/TypeScript (js-debug), C/C++/Rust (lldb-dap), Java (java-debug), Scala (Metals), WebAssembly (lldb-dap), or any DAP adapter via `dap.json`\n- **Comprehensive DAP coverage** — 35+ DAP requests: breakpoints, stepping, goto, memory read/write, disassembly, and more\n- **Breakpoints** — conditional, logpoints, hit-count, function, data (watchpoints), exception, run-to-cursor (`continue_until`)\n- **Multi-session** — debug multiple programs simultaneously, with child session routing (js-debug)\n- **Remote debugging** — attach to debugpy, JDWP, or Node inspector running on another machine or container\n\n### LLM / MCP Integration\n- **64 MCP tools** — the full debug session exposed to Claude or any LLM\n- **Capability-gated tools** — tools automatically shown/hidden based on adapter capabilities\n- **Compound tools** — `get_debug_context` (orient in one call), `step_until`, `step_until_change`, `run_until_exception`, `explain_exception`, `get_call_tree`, `compare_snapshots`, `find_first_change`\n- **Execution timeline** — every stop recorded with changed variables and stack summary\n- **Watch expressions** — evaluated automatically at every breakpoint, manageable by LLM or UI\n- **Annotations & findings** — pin notes to source lines, record conclusions visible in the UI\n- **Session export/import** — save and restore debugging knowledge across sessions\n\n### CLI Control\n- **Full CLI** — 13 subcommands to drive sessions from a second terminal without the web UI\n- **Auto-discovery** — port file at `~/.debugium/port`, session logs in `~/.debugium/sessions/`\n\n---\n\n## Install\n\n### Claude Code Plugin (recommended)\n\n```\n/plugin marketplace add Algiras/debugium\n/plugin install debugium@debugium\n```\n\nThen add to your project's `.mcp.json` (see [MCP Tools](#mcp-tools) below).\n\n### macOS / Linux binary\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/Algiras/debugium/main/install.sh | bash\n```\n\n### From source\n\n```bash\n# Prerequisites: Rust stable + wasm-pack\ncargo install wasm-pack\n\n# Build UI\nwasm-pack build crates/debugium-ui --target web --out-dir pkg\ncp crates/debugium-ui/pkg/cm_init.js         crates/debugium-ui/dist/pkg/\ncp crates/debugium-ui/pkg/debugium_ui.js      crates/debugium-ui/dist/pkg/\ncp crates/debugium-ui/pkg/debugium_ui_bg.wasm crates/debugium-ui/dist/pkg/\n\n# Build & install server\ncargo install --path crates/debugium-server\n```\n\n---\n\n## Usage\n\n### Debug a Python file\n\n```bash\ndebugium launch my_script.py --adapter python\n```\n\n### Debug a Node.js / TypeScript file\n\n```bash\ndebugium launch app.js --adapter node\ndebugium launch app.ts --adapter typescript\n```\n\n### Debug C / C++ / Rust\n\n```bash\n# C or C++ (compile with -g for debug info)\ncc -g -O0 main.c -o main && debugium launch ./main --adapter lldb\nc++ -g -O0 main.cpp -o main && debugium launch ./main --adapter lldb\n\n# Rust\ncargo build && debugium launch target/debug/my_binary --adapter lldb\n```\n\n### Debug Java / Scala\n\n```bash\n# Java (requires microsoft/java-debug adapter)\ndebugium launch MainClass --adapter java\n\n# Scala (connect to a running Metals DAP server)\ndebugium launch build-target --adapter metals\ndebugium launch build-target --adapter metals:5005  # custom port\n```\n\n### Attach to a running process (remote debugging)\n\n```bash\n# Python (debugpy listening on port 5678)\ndebugium attach --port 5678 --adapter python\n\n# Java (JDWP on port 5005)\ndebugium attach --port 5005 --adapter java\n\n# Node.js (inspector on port 9229)\ndebugium attach --port 9229 --adapter node\n```\n\nOr via MCP: `attach_session(port=5678, adapter=\"python\", breakpoints=[\"/path/app.py:42\"])`\n\n### Use a custom adapter via dap.json\n\n```bash\n# Create a dap.json (see dap.json.example) then:\ndebugium launch my_program --config ./dap.json\n\n# Or place dap.json in cwd / .debugium/ for auto-discovery:\ndebugium launch my_program   # finds ./dap.json automatically\n```\n\n### Set initial breakpoints\n\n```bash\ndebugium launch my_script.py --adapter python \\\n  --breakpoint /abs/path/my_script.py:42 \\\n  --breakpoint /abs/path/helpers.py:15\n```\n\n### Enable LLM / MCP integration\n\nAdd a `.mcp.json` to your project root (Claude Code picks this up automatically):\n\n```json\n{\n  \"mcpServers\": {\n    \"debugium\": {\n      \"command\": \"debugium\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nThen launch the session normally — the MCP server connects to whichever port is active:\n\n```bash\ndebugium launch my_script.py --adapter python --breakpoint /abs/path/my_script.py:42\n```\n\nClaude Code will now have access to all Debugium MCP tools. See [CLAUDE.md](CLAUDE.md) for\nthe recommended workflow and [SKILL.md](SKILL.md) for the full tool reference.\n\n---\n\n## CLI Control Commands\n\nOnce a session is running (`debugium launch …`), you can drive it from a second terminal — or from an LLM agent — without touching the web UI.\n\nPort is auto-discovered from `~/.debugium/port`; override with `--port`.\n\n### Global flags (all subcommands)\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `--port PORT` | `~/.debugium/port` | Server port to connect to |\n| `--session ID` | `default` | Session to target |\n| `--json` | off | Print raw JSON instead of human-readable output |\n\n### Inspection\n\n```bash\ndebugium sessions                  # list active sessions\ndebugium threads                   # list threads\ndebugium stack                     # show call stack\ndebugium vars                      # show local variables (auto-resolves top frame)\ndebugium vars --frame-id 2         # show variables for a specific frame\ndebugium eval \"len(fibs)\"          # evaluate expression in top frame\ndebugium eval \"x + 1\" --frame-id 2\ndebugium source path/to/file.py    # print full source file\ndebugium source path/to/file.py --line 43  # windowed ±10 lines with → marker\ndebugium context                   # full snapshot: paused-at, stack, locals, source, breakpoints\ndebugium context --compact         # same but truncated (3 frames, 10 vars)\n```\n\n### Breakpoints\n\n```bash\ndebugium bp set FILE:LINE [FILE:LINE …]   # set breakpoints (replaces existing in that file)\ndebugium bp list                          # list all breakpoints\ndebugium bp clear                         # clear all breakpoints\n```\n\n### Execution control\n\n```bash\ndebugium continue                  # resume execution\ndebugium step over                 # step over (next line)\ndebugium step in                   # step into a function call\ndebugium step out                  # step out of current function\n```\n\n### UI annotations (visible in the web UI)\n\n```bash\ndebugium annotate FILE:LINE \"message\" [--color info|warning|error]\ndebugium finding \"message\"         [--level  info|warning|error]\n```\n\n### Example workflow\n\n```bash\n# Terminal A — start the session\ndebugium launch tests/target_python.py --adapter python \\\n  --breakpoint \"$(pwd)/tests/target_python.py:43\"\n\n# Terminal B (or LLM agent) — inspect and drive it\ndebugium sessions\ndebugium stack\ndebugium vars\ndebugium eval \"len(fibs)\"\ndebugium bp set tests/target_python.py:49\ndebugium continue                  # runs to line 49\ndebugium vars\ndebugium step over\ndebugium context --json            # machine-readable snapshot\ndebugium annotate tests/target_python.py:43 \"called here\" --color info\ndebugium finding \"fibs has 10 elements\" --level info\ndebugium bp clear\n```\n\n---\n\n## MCP Tools\n\nWhen connected via MCP, 64 tools are available. Key ones:\n\n| Category | Tools |\n|----------|-------|\n| **Orient** | `get_debug_context` ★ (paused location + locals + stack + source in one call) |\n| **Breakpoints** | `set_breakpoint`, `set_breakpoints`, `set_logpoint`, `list_breakpoints`, `clear_breakpoints`, `set_function_breakpoints`, `set_exception_breakpoints`, `set_data_breakpoint`, `list_data_breakpoints`, `clear_data_breakpoints`, `breakpoint_locations` |\n| **Execution** | `continue_execution`, `step_over`, `step_in`, `step_out`, `pause`, `goto`, `disconnect`, `terminate`, `restart` |\n| **Inspection** | `get_stack_trace`, `get_scopes`, `get_variables`, `evaluate`, `get_threads`, `get_source`, `get_capabilities`, `loaded_sources`, `source_by_reference`, `step_in_targets` |\n| **Mutation** | `set_variable`, `set_expression` |\n| **Output** | `get_console_output`, `wait_for_output` (with `from_line` to avoid stale matches) |\n| **Memory** | `read_memory`, `write_memory`, `disassemble` (native debugging) |\n| **History** | `get_timeline`, `get_variable_history`, `compare_snapshots`, `find_first_change` |\n| **Annotations** | `annotate`, `get_annotations`, `add_finding`, `get_findings` |\n| **Watches** | `add_watch`, `remove_watch`, `get_watches` |\n| **Compound** | `step_until`, `step_until_change`, `continue_until`, `run_until_exception`, `explain_exception`, `get_call_tree`, `restart_frame` |\n| **Session** | `get_sessions`, `list_sessions`, `launch_session`, `attach_session`, `stop_session`, `export_session`, `import_session` |\n| **Control** | `goto_targets`, `cancel_request` |\n\n> **Note**: `step_over`, `step_in`, and `step_out` are **blocking** — they wait for the\n> adapter to pause before returning. Safe to chain back-to-back without sleeps.\n> `continue_execution` returns `console_line_count` for use with `wait_for_output`.\n> Tools like `read_memory`, `goto`, and `restart_frame` only appear when the adapter supports them.\n\nSee [SKILL.md](SKILL.md) for the full reference with input schemas.\n\n---\n\n## Keyboard Shortcuts\n\n| Key | Action |\n|-----|--------|\n| `F5` | Continue |\n| `F10` | Step Over |\n| `F11` | Step Into |\n| `Shift+F11` | Step Out |\n| `Ctrl/⌘+D` | Toggle dark/light mode |\n\n---\n\n## Architecture\n\n```\ndebugium-server (Rust + Axum)\n├── DAP proxy     — spawns / attaches to debug adapters (debugpy, js-debug, lldb-dap, java-debug, Metals, custom)\n├── HTTP API      — /state, /sessions, /annotations, /findings, /watches, /timeline\n├── WebSocket     — broadcasts DAP events + enriched stop data (changed vars, timeline) to UI\n├── MCP stdio     — JSON-RPC 2.0 server exposing 64 tools for LLM integration\n├── CLI control   — 13 subcommands to drive sessions from a second terminal\n└── ~/.debugium/  — port file, session logs (events.ndjson), debug log\n\ndebugium-ui (Leptos + WASM)\n├── CodeMirror 6  — source viewer with breakpoint gutters, exec arrow, LLM annotations, multi-tab\n├── Reactive panels — Variables, Stack, Breakpoints, Findings, Watch, Timeline, Console (18 components)\n└── WebSocket     — receives events, sends DAP commands, auto-reconnects with status indicator\n```\n\n---\n\n## Supported Languages & Adapters\n\n| Language | `--adapter` flag | Prerequisite | Verified |\n|----------|-----------------|--------------|----------|\n| Python | `python` / `debugpy` | `pip install debugpy` | ✅ |\n| Node.js | `node` / `js` | js-debug (bundled or build from [vscode-js-debug](https://github.com/nicolo-ribaudo/nicolo-ribaudo-js-debug)) | ✅ |\n| TypeScript | `typescript` / `ts` / `tsx` | js-debug + `tsx` or `ts-node` in PATH | ✅ |\n| C / C++ | `lldb` / `codelldb` | `lldb-dap` (Xcode on macOS; `apt install lldb` on Linux) | ✅ |\n| Rust | `lldb` / `rust` | `lldb-dap` + `cargo build` | ✅ |\n| Java | `java` / `jvm` | [microsoft/java-debug](https://github.com/nicolo-ribaudo/nicolo-ribaudo-java-debug) adapter JAR | ✅ |\n| Scala | `metals` / `scala` | Running [Metals](https://scalameta.org/metals/) DAP server | ⚠️ (requires running Metals) |\n| WebAssembly | `wasm` | `lldb-dap` (LLVM ≥16) | ⚠️ (requires WASM-aware LLVM) |\n| Any DAP adapter | `--config dap.json` | See `dap.json.example` | ✅ |\n\n### Remote debugging\n\nConnect to a DAP server running on another machine (or in a container):\n\n```json\n{\n  \"adapterId\": \"debugpy\",\n  \"request\": \"attach\",\n  \"host\": \"192.168.1.100\",\n  \"port\": 5678,\n  \"pathMappings\": [{ \"localRoot\": \".\", \"remoteRoot\": \"/app\" }]\n}\n```\n\n```bash\ndebugium launch app.py --config remote.json\n```\n\n---\n\n## License\n\nMIT\n",
  "bytes": 13500,
  "sha": "1979a07ff158a4d4e43e55fa69c4f6c583180c478280821acbcf7263835fb8ae",
  "repo_slug": "algiras/debugium",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_algiras_debugium_b5c5e2cc/readme"
}