debugium

Debugium

リアルタイム Web UI と MCP 経由の LLM 統合を備えた多言語デバッガーです。

ブラウザーから Python、JavaScript、TypeScript、C、C++、Rust、Java、Scala、WebAssembly のプログラムをデバッグできます。Model Context Protocol による AI 主導の分析にも対応しています。

---

機能

Web UI

• リアルタイム Web UI — ソースビューアー、ブレークポイント、変数（再帰的な展開）、コールスタック、コンソール、タイムライン、ウォッチ式、検出結果を WebSocket 経由でリアルタイムに更新します
• 複数タブ対応のソースビューアー — 複数のファイルを開き、スタックフレームをクリックして移動できます
• 変数検索 — 再帰的な展開に対応し、名前で変数を絞り込めます
• 変更された変数の強調表示 — 前回の停止以降に変更された変数をオレンジ色で表示します
• スレッドセレクター — マルチスレッドプログラム内のスレッドを切り替えられます
• パネルの折りたたみとサイズ変更 — ドラッグしてサイズを変更し、切り替えて折りたためます。Slim／Standard／Full のレイアウトプリセットに対応しています
• ダークモード／ライトモードの切り替え
• 自動再接続 — WebSocket が切断された後に UI が再接続し、状態を視覚的に表示します
• キーボードショートカット — F5 で続行、F10 でステップオーバー、F11 でステップイン、Shift+F11 でステップアウト、Ctrl/Cmd+D でダークモード
• ボタンアニメーション — デバッグコマンドの実行中はスピナーを表示し、完了時にフラッシュ表示します

デバッグ

• 多言語対応 — Python（debugpy）、Node.js/TypeScript（js-debug）、C/C++/Rust（lldb-dap）、Java（java-debug）、Scala（Metals）、WebAssembly（lldb-dap）、または dap.json を介した任意の DAP アダプター
• 包括的な DAP 対応 — ブレークポイント、ステップ実行、移動、メモリの読み書き、逆アセンブルなど、35 種類以上の DAP リクエストに対応します
• ブレークポイント — 条件付き、ログポイント、ヒットカウント、関数、データ（ウォッチポイント）、例外、カーソル位置まで実行（continue_until）
• 複数セッション — 複数のプログラムを同時にデバッグでき、子セッションへのルーティング（js-debug）にも対応します
• リモートデバッグ — 別のマシンやコンテナー上で実行中の debugpy、JDWP、Node インスペクターに接続できます

LLM／MCP 統合

• 64 個の MCP ツール — デバッグセッション全体を Claude または任意の LLM に公開します
• 機能に応じて表示されるツール — アダプターの機能に基づき、ツールを自動的に表示または非表示にします
• 複合ツール — get_debug_context（1 回の呼び出しで状況を把握）、step_until、step_until_change、run_until_exception、explain_exception、get_call_tree、compare_snapshots、find_first_change
• 実行タイムライン — 停止のたびに、変更された変数とスタックの概要を記録します
• ウォッチ式 — すべてのブレークポイントで自動評価され、LLM または UI から管理できます
• 注釈と検出結果 — ソース行にメモをピン留めし、UI で確認できる結論を記録します
• セッションのエクスポート／インポート — セッションをまたいでデバッグの知見を保存、復元できます

CLI 制御

• 完全な CLI — 13 個のサブコマンドを使って、Web UI を使わずに別のターミナルからセッションを操作できます
• 自動検出 — ~/.debugium/port にポートファイルを、~/.debugium/sessions/ にセッションログを保存します

---

インストール

Claude Code プラグイン（推奨）

/plugin marketplace add Algiras/debugium
/plugin install debugium@debugium

その後、プロジェクトの .mcp.json に追加してください（下記の MCP ツールを参照）。

macOS／Linux バイナリ

curl -fsSL https://raw.githubusercontent.com/Algiras/debugium/main/install.sh | bash

ソースから

# Prerequisites: Rust stable + wasm-pack
cargo install wasm-pack

# Build UI
wasm-pack build crates/debugium-ui --target web --out-dir pkg
cp crates/debugium-ui/pkg/cm_init.js         crates/debugium-ui/dist/pkg/
cp crates/debugium-ui/pkg/debugium_ui.js      crates/debugium-ui/dist/pkg/
cp crates/debugium-ui/pkg/debugium_ui_bg.wasm crates/debugium-ui/dist/pkg/

# Build & install server
cargo install --path crates/debugium-server

---

使い方

Python ファイルをデバッグする

debugium launch my_script.py --adapter python

Node.js／TypeScript ファイルをデバッグする

debugium launch app.js --adapter node
debugium launch app.ts --adapter typescript

C／C++／Rust をデバッグする

# C or C++ (compile with -g for debug info)
cc -g -O0 main.c -o main && debugium launch ./main --adapter lldb
c++ -g -O0 main.cpp -o main && debugium launch ./main --adapter lldb

# Rust
cargo build && debugium launch target/debug/my_binary --adapter lldb

Java／Scala をデバッグする

# Java (requires microsoft/java-debug adapter)
debugium launch MainClass --adapter java

# Scala (connect to a running Metals DAP server)
debugium launch build-target --adapter metals
debugium launch build-target --adapter metals:5005  # custom port

実行中のプロセスに接続する（リモートデバッグ）

# Python (debugpy listening on port 5678)
debugium attach --port 5678 --adapter python

# Java (JDWP on port 5005)
debugium attach --port 5005 --adapter java

# Node.js (inspector on port 9229)
debugium attach --port 9229 --adapter node

または MCP 経由で実行します：attach_session(port=5678, adapter="python", breakpoints=["/path/app.py:42"])

dap.json を介してカスタムアダプターを使用する

# Create a dap.json (see dap.json.example) then:
debugium launch my_program --config ./dap.json

# Or place dap.json in cwd / .debugium/ for auto-discovery:
debugium launch my_program   # finds ./dap.json automatically

初期ブレークポイントを設定する

debugium launch my_script.py --adapter python \
  --breakpoint /abs/path/my_script.py:42 \
  --breakpoint /abs/path/helpers.py:15

LLM / MCP 統合を有効にする

プロジェクトのルートに .mcp.json を追加します（Claude Code が自動的に読み込みます）。

{
  "mcpServers": {
    "debugium": {
      "command": "debugium",
      "args": ["mcp"]
    }
  }
}

その後、通常どおりセッションを起動します。MCP サーバーは、その時点でアクティブなポートに接続します。

debugium launch my_script.py --adapter python --breakpoint /abs/path/my_script.py:42

これで、Claude Code からすべての Debugium MCP ツールを利用できるようになります。推奨ワークフローについては CLAUDE.md を、すべてのツールのリファレンスについては SKILL.md を参照してください。

---

CLI 制御コマンド

セッションの実行中（debugium launch …）は、Web UI に触れることなく、2 つ目のターミナルまたは LLM エージェントから操作できます。

ポートは ~/.debugium/port から自動検出されます。--port で上書きできます。

グローバルフラグ（すべてのサブコマンド）

フラグ	デフォルト	説明
--port PORT	~/.debugium/port	接続先のサーバーポート
--session ID	default	操作対象のセッション
--json	オフ	人間が読みやすい形式ではなく、生の JSON を出力します

状態の確認

debugium sessions                  # list active sessions
debugium threads                   # list threads
debugium stack                     # show call stack
debugium vars                      # show local variables (auto-resolves top frame)
debugium vars --frame-id 2         # show variables for a specific frame
debugium eval "len(fibs)"          # evaluate expression in top frame
debugium eval "x + 1" --frame-id 2
debugium source path/to/file.py    # print full source file
debugium source path/to/file.py --line 43  # windowed ±10 lines with → marker
debugium context                   # full snapshot: paused-at, stack, locals, source, breakpoints
debugium context --compact         # same but truncated (3 frames, 10 vars)

ブレークポイント

debugium bp set FILE:LINE [FILE:LINE …]   # set breakpoints (replaces existing in that file)
debugium bp list                          # list all breakpoints
debugium bp clear                         # clear all breakpoints

実行制御

debugium continue                  # resume execution
debugium step over                 # step over (next line)
debugium step in                   # step into a function call
debugium step out                  # step out of current function

UI 注釈（Web UI に表示）

debugium annotate FILE:LINE "message" [--color info|warning|error]
debugium finding "message"         [--level  info|warning|error]

ワークフローの例

# Terminal A — start the session
debugium launch tests/target_python.py --adapter python \
  --breakpoint "$(pwd)/tests/target_python.py:43"

# Terminal B (or LLM agent) — inspect and drive it
debugium sessions
debugium stack
debugium vars
debugium eval "len(fibs)"
debugium bp set tests/target_python.py:49
debugium continue                  # runs to line 49
debugium vars
debugium step over
debugium context --json            # machine-readable snapshot
debugium annotate tests/target_python.py:43 "called here" --color info
debugium finding "fibs has 10 elements" --level info
debugium bp clear

---

MCP ツール

MCP 経由で接続すると、64 個のツールを利用できます。主なツールは次のとおりです。

カテゴリ	ツール
状況把握	get_debug_context ★（停止位置＋ローカル変数＋スタック＋ソースを 1 回の呼び出しで取得）
ブレークポイント	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
実行	continue_execution、step_over、step_in、step_out、pause、goto、disconnect、terminate、restart
状態の確認	get_stack_trace、get_scopes、get_variables、evaluate、get_threads、get_source、get_capabilities、loaded_sources、source_by_reference、step_in_targets
変更	set_variable、set_expression
出力	get_console_output、wait_for_output（古い一致を避けるための from_line 指定に対応）
メモリ	read_memory、write_memory、disassemble（ネイティブデバッグ）
履歴	get_timeline、get_variable_history、compare_snapshots、find_first_change
注釈	annotate、get_annotations、add_finding、get_findings
ウォッチ	add_watch、remove_watch、get_watches
複合操作	step_until、step_until_change、continue_until、run_until_exception、explain_exception、get_call_tree、restart_frame
セッション	get_sessions、list_sessions、launch_session、attach_session、stop_session、export_session、import_session
制御	goto_targets、cancel_request

注：step_over、step_in、step_out はブロッキングです。アダプターが一時停止するまで待ってから返ります。スリープを挟まずに続けて呼び出しても安全です。 continue_execution は、wait_for_output で使用する console_line_count を返します。 read_memory、goto、restart_frame などのツールは、アダプターが対応している場合にのみ表示されます。

入力スキーマを含む完全なリファレンスについては、SKILL.md を参照してください。

---

キーボードショートカット

キー	操作
F5	続行
F10	ステップオーバー
F11	ステップイン
Shift+F11	ステップアウト
Ctrl/⌘+D	ダークモード／ライトモードを切り替え

---

アーキテクチャ

debugium-server (Rust + Axum)
├── DAP proxy     — spawns / attaches to debug adapters (debugpy, js-debug, lldb-dap, java-debug, Metals, custom)
├── HTTP API      — /state, /sessions, /annotations, /findings, /watches, /timeline
├── WebSocket     — broadcasts DAP events + enriched stop data (changed vars, timeline) to UI
├── MCP stdio     — JSON-RPC 2.0 server exposing 64 tools for LLM integration
├── CLI control   — 13 subcommands to drive sessions from a second terminal
└── ~/.debugium/  — port file, session logs (events.ndjson), debug log

debugium-ui (Leptos + WASM)
├── CodeMirror 6  — source viewer with breakpoint gutters, exec arrow, LLM annotations, multi-tab
├── Reactive panels — Variables, Stack, Breakpoints, Findings, Watch, Timeline, Console (18 components)
└── WebSocket     — receives events, sends DAP commands, auto-reconnects with status indicator

---

対応言語とアダプター

言語	--adapter フラグ	前提条件	検証済み
Python	python / debugpy	pip install debugpy	✅
Node.js	node / js	js-debug（バンドル版、または vscode-js-debug からビルド）	✅
TypeScript	typescript / ts / tsx	PATH に js-debug と tsx または ts-node があること	✅
C / C++	lldb / codelldb	lldb-dap（macOS では Xcode、Linux では apt install lldb）	✅
Rust	lldb / rust	lldb-dap と cargo build	✅
Java	java / jvm	microsoft/java-debug アダプター JAR	✅
Scala	metals / scala	起動中の Metals DAP サーバー	⚠️（Metals の起動が必要です）
WebAssembly	wasm	lldb-dap（LLVM ≥16）	⚠️（WASM 対応の LLVM が必要です）
任意の DAP アダプター	--config dap.json	dap.json.example を参照してください	✅

リモートデバッグ

別のマシン（またはコンテナー）で実行中の DAP サーバーに接続します。

{
  "adapterId": "debugpy",
  "request": "attach",
  "host": "192.168.1.100",
  "port": 5678,
  "pathMappings": [{ "localRoot": ".", "remoteRoot": "/app" }]
}

debugium launch app.py --config remote.json

---

ライセンス

MIT