textual-debugger 0.1.5__tar.gz → 0.2.0__tar.gz

{textual_debugger-0.1.5 → textual_debugger-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: textual-debugger
-Version: 0.1.5
+Version: 0.2.0
 Summary: A TUI Python debugger based on textual and debugpy
 Author-email: Al Danial <al.danial@gmail.com>
 License: textual-debugger is licensed to you under the MIT/X Consortium license:
@@ -67,12 +67,18 @@ Dynamic: license-file
 # `textual-debugger`
 
 `textual-debugger` (the package) provides `tdb` (the command-line tool and module),
-a full-featured terminal-based Python debugger.
-
-`tdb` is built with [textual](https://github.com/Textualize/textual)
-and [debugpy](https://github.com/microsoft/debugpy) (the Debug Adapter Protocol engine behind
-VS Code's Python debugger). It provides a rich interactive interface for stepping through code,
-inspecting variables, managing breakpoints, and evaluating expressions in complex Python programs.
+a full-featured terminal-based debugger for Python and other languages
+with a Debug Adapter Protocol (DAP) implementation. C and C++ support (via
+`gdb` or `lldb-dap`) is built in.
+
+`tdb` is built with [textual](https://github.com/Textualize/textual) and speaks
+DAP to a pluggable debug adapter: [debugpy](https://github.com/microsoft/debugpy)
+(the engine behind VS Code's Python debugger) for Python,
+[GDB's DAP mode](https://sourceware.org/gdb/current/onlinedocs/gdb.html/Debugger-Adapter-Protocol.html) or
+[lldb-dap](https://lldb.llvm.org/resources/lldbdap.html)
+for compiled code. It provides a rich interactive interface for stepping through
+code, inspecting variables, managing breakpoints, and evaluating expressions in
+complex programs.
 
 - PyPI: https://pypi.org/project/textual-debugger/
 - GitHub: https://github.com/AlDanial/tdb
@@ -83,6 +89,10 @@ MIT License.  Copyright 2026 by Al Danial.
 
 `tdb`:
 
+- debugs multiple languages through the Debug Adapter Protocol: Python (via `debugpy`,
+the richest feature set) and C/C++ (via `gdb -i dap` or `lldb-dap`), with the language
+auto-detected from the target (ref. [Multi-Language Debugging](#multi-language-debugging)).
+
 - supports debugging of synchronous, asynchronous, multi-threaded, and multi-process Python code.
 It specifically supports modules
     - `asyncio` (with a built-in async task inspector and task wait graph)
@@ -169,6 +179,16 @@ tdb my_program.py
 # debug with arguments
 tdb my_program.py arg1 arg2
 
+# debug a C/C++ (or other native) executable built with -g.  The ELF/Mach-O/PE
+# binary is auto-detected and debugged through GDB's DAP mode (GDB >= 14)
+tdb ./myprog arg1 arg2
+
+# same, but using lldb-dap (LLVM >= 17) instead of gdb
+tdb --adapter lldb-dap ./myprog
+
+# force the language when auto-detection can't tell (e.g. an extensionless script)
+tdb --lang python ./mytool
+
 # add breakpoints at lines 20 and 35 of `my_program.py` and line 14
 # of `module.py` (when -k is given, --no-stop-on-entry is set and the
 # program runs to the first breakpoint)
@@ -210,6 +230,79 @@ Alternatively, use the module entry point:
 python -m tdb my_program.py
 ```
 
+## Multi-Language Debugging
+
+`tdb` debugs any language that has a Debug Adapter Protocol backend. Two
+languages are supported out of the box:
+
+| Language | Adapter(s) | How to get the adapter | Feature level |
+|----------|------------|------------------------|---------------|
+| Python | `debugpy` (default) | installed with `textual-debugger` | everything in this README |
+| C / C++ (any native binary) | `gdb` (default), `lldb-dap` (alternate) | `gdb -i dap` requires GDB ≥ 14; `lldb-dap` ships with LLVM ≥ 17 (e.g. `apt install lldb`) | core debugging: breakpoints, stepping, stack, variables, evaluate console |
+
+### Language detection and selection
+
+The language is auto-detected from the debug target:
+
+1. File extension: `.py` → Python.
+2. Native executables (ELF, Mach-O, PE magic bytes) → C/C++.
+3. A `#!...python` shebang → Python.
+4. C/C++/Rust *source* files (`.c`, `.cpp`, `.rs`, …) produce an error with a
+   hint: compile with debug info (`g++ -g -O0`) and debug the binary.
+5. Anything else produces an error naming the `--lang` override.
+
+`--lang` forces the language; `--adapter` picks a non-default adapter within
+it (`tdb --lang cpp --adapter lldb-dap ./myprog`).
+
+> **Migration note:** extensionless Python scripts without a `python` shebang
+> were previously assumed to be Python; they now require `--lang python`.
+
+### Adapters are found on `PATH`
+
+`tdb` does not download or bundle adapters. If the adapter executable isn't
+found, the error names the package to install. To use an adapter from a
+non-standard location, or change a language's default adapter, add to
+`config.json` (see [Configuration](#configuration)):
+
+```json
+{
+  "adapters": {"lldb-dap": "/opt/llvm/bin/lldb-dap"},
+  "default_adapters": {"cpp": "lldb-dap"}
+}
+```
+
+### What works for non-Python languages
+
+Core debugging works identically for every language: breakpoints (incl.
+conditions and persistence), stepping, continue/pause, run-to-cursor, stack
+navigation, variable inspection, the evaluate console, syntax highlighting,
+and the JSON-RPC / MCP programmatic modes.
+
+Python-specific features are hidden or return a clear "not supported for this
+language" message when debugging other languages: statement-granularity
+stepping (non-Python languages always step per line), the async task /
+process inspectors and wait graph, the evaluate console's trailing-`?` help,
+remote attach (`-r`), `--python`/`--pv`, `--no-subprocess`,
+automatic child-process attachment, and the post-mortem / `tdb.breakpoint()`
+hooks (those hooks live inside Python programs by nature). `--terminal` is
+currently ignored for non-Python targets.
+
+### C/C++ tips
+
+- Compile with `-g` (ideally `-g -O0`). If no breakpoint in a file can be
+  bound, `tdb` prints a console warning suggesting the program may lack
+  debug info.
+- Stack frames pointing into system libraries often have no source on disk;
+  the Code View shows a `<Could not read …>` placeholder while the stack,
+  variables, and evaluate console remain fully usable.
+- GDB (the default adapter) has the most complete libstdc++
+  pretty-printing. `lldb-dap` (via `--adapter lldb-dap`) also debugs
+  GCC-built binaries fine — DWARF is compiler-neutral.
+- **GDB evaluate-console quirk:** GDB's DAP treats REPL input as CLI
+  commands, so evaluate expressions with an explicit `print`, e.g.
+  `print x` rather than bare `x` (bare `x` collides with GDB's
+  examine-memory command). `lldb-dap` evaluates bare expressions directly.
+
 ## Layout
 
 ```
@@ -238,7 +331,7 @@ The footer shows the most relevant keybindings for the current mode.
 ### Navigation and Keybindings
 
 
-The Code View shows syntax-highlighted Python source with line numbers.
+The Code View shows syntax-highlighted source (lexer chosen per language) with line numbers.
 A cursor line (blue) tracks your position; the current execution line is highlighted in gold.
 
 **View focus shortcuts (global):**
@@ -330,6 +423,9 @@ lands on `print(results)`, not on each interior sub-line of the `gather` call. S
 stops on each physical line--useful for inspecting how a complex expression is built up.
 The choice is saved to `~/.config/tdb/config.json`.
 
+Statement mode requires a source-language model and is currently Python-only;
+other languages always step per line (the Step Mode menu says so if you try).
+
 ### Breakpoints
 
 Click the gutter in the Code View to toggle a breakpoint, or press `b` in Debug mode.
@@ -387,6 +483,15 @@ interactive evaluation of expressions in the current scope:
 
 Variable values set here are reflected in the running code.
 
+### Cut / Paste
+
+Expression for the Evaluate Console are often copied from the Code View.
+Doing this in `tdb` differs from traditional terminal behavior, because `textual` applications
+capture mouse events for their own use.
+
+Instead, hold the `Shift` key while performing your conventional cut/paste keystrokes or mouse
+operation to get the expected behavior.
+
 ### Console Output
 
 The Console View captures stdout (normal text) and stderr (red text) from the debuggee
@@ -754,7 +859,7 @@ curl -s -X POST http://127.0.0.1:8150/rpc \
 | `set_breakpoint` | `["file:line"]` or `["file:line", "condition", "hit_condition"]` | Set a breakpoint |
 | `remove_breakpoint` | `["file:line"]` | Remove a breakpoint |
 | `list_breakpoints` | `[]` | Show all breakpoints |
-| `continue` | `[]` or `[timeout_s]` | Resume execution; on timeout returns `"still running — call pause or wait again"` (success) |
+| `continue` | `[]` or `[timeout_s]` | Resume execution; on timeout returns `"still running--call pause or wait again"` (success) |
 | `next` | `[]` or `[timeout_s]` | Step over |
 | `step_in` | `[]` or `[timeout_s]` | Step into |
 | `step_out` | `[]` or `[timeout_s]` | Step out |
@@ -793,7 +898,7 @@ Each is JSON with `event`, `data`, and `timestamp` fields.
 tdb ships a Model Context Protocol (MCP) server (`tdb-mcp`) that exposes
 the debugger as a curated set of tools an AI agent can call. The MCP
 server is a third in-process consumer of the same dispatch handlers the
-TUI and the HTTP server use — so an agent gets the same lock semantics,
+TUI and the HTTP server use so an agent gets the same lock semantics,
 including the pause-during-continue bypass, and the same DAP-backed
 inspection surface.
 
@@ -832,17 +937,24 @@ client expects to launch servers.
 | Breakpoints | `set_breakpoint(spec, condition?, hit_condition?)`, `remove_breakpoint(spec)`, `list_breakpoints()` |
 | Differentiators | `threads(thread_id?)`, `tasks(task_name?)`, `processes(name_or_pid?)`, `wait_graph()` |
 
-`control` is intentionally one tool that takes an action enum — the six
+`control` is intentionally one tool that takes an action enum. The six
 underlying RPC actions share a return shape, and agents perform
 measurably better with a small surface than with one tool per action.
 `threads` / `tasks` / `processes` overload list-vs-inspect via a
 single optional argument for the same reason.
 
+`debug_launch` accepts optional `lang` and `adapter` parameters mirroring the
+CLI's `--lang`/`--adapter`; when omitted, the language is auto-detected from
+`program`, so an agent can hand it a compiled binary directly. The
+`tasks`/`processes`/`wait_graph` tools stay registered for every language but
+return a structured "not supported when debugging C/C++"-style error for
+non-Python debuggees.
+
 ### Agent flow for a long-running step
 
 ```
 agent → control(action="continue", timeout_s=30)
-mcp   → "still running — call pause or wait again"
+mcp   → "still running, call pause or wait again"
 agent → control(action="pause")        # OR: control(action="wait_for_stop", timeout_s=30)
 mcp   → "<file>:<line>"
 agent → inspect(["x", "len(buf)"])
@@ -851,7 +963,7 @@ mcp   → "x = 7\nlen(buf) = 1024"
 
 `pause` bypasses the dispatch lock so it can interrupt a `continue`
 that's still mid-flight (HTTP and MCP share the same `NO_LOCK_ACTIONS`
-policy — see `tdb/server/app.py`).
+policy; see `tdb/server/app.py`).
 
 ### Security caveat
 
@@ -860,22 +972,23 @@ execution in the debuggee process**. This is inherent to a debugger and
 not a tdb-specific concern, but MCP clients (and the humans running
 them) should apply appropriate permission models: don't auto-approve
 `inspect` against untrusted expressions, and don't expose `tdb-mcp` on
-a network — stdio transport only by design.
+a network (stdio transport only by design).
 
 ### Deferred / out of scope (v1)
 
-- SSE-style event push — `control` and `wait_for_stop` make polling
+- SSE-style event push: `control` and `wait_for_stop` make polling
   efficient enough; events would also need uneven MCP-client support.
-- HTTP / streamable-HTTP transports — would require auth (which the
+- HTTP / streamable-HTTP transports: would require auth (which the
   HTTP RPC server also currently lacks); stdio inherits the trust of
   the process that spawned it.
-- Multi-session — one debug session per MCP process.
+- Multi-session: one debug session per MCP process.
 
 ## CLI Reference
 
 ```
 usage: tdb [-h] [-v] [-r [HOST:]PORT] [--cwd CWD] [--no-stop-on-entry]
            [--no-just-my-code] [--no-subprocess] [--python PYTHON] [--pv]
+           [--lang LANGUAGE] [--adapter ADAPTER]
            [--keybindings {default,vim,emacs}]
            [--terminal {xterm,konsole,gnome-terminal,ghostty,kitty,iterm2,warp,wezterm,terminator}]
            [--local-root PATH] [--remote-root PATH]
@@ -891,8 +1004,10 @@ usage: tdb [-h] [-v] [-r [HOST:]PORT] [--cwd CWD] [--no-stop-on-entry]
 | `-k`, `--breakpoint FILE:LINE|LINE` | Set a breakpoint (may be repeated). Passing `-k` implies `--no-stop-on-entry` so the program runs straight to the first breakpoint. |
 | `--no-stop-on-entry` | Do not pause at the first line (default: stop on entry; automatic when `-k` is given) |
 | `--cwd DIR` | Working directory for the debuggee |
-| `--python PATH` | Python interpreter for the debuggee |
+| `--python PATH` | Python interpreter for the debuggee (Python targets only) |
 | `--pv` | Shorthand for --python .venv/bin/python |
+| `--lang LANGUAGE` | Debuggee language (`python`, `cpp`); default: auto-detect from the target |
+| `--adapter ADAPTER` | Debug adapter within the language (e.g. `--lang cpp --adapter lldb-dap`); default: the language's standard adapter |
 | `--no-just-my-code` | Step into stdlib/site-packages code instead of skipping it
   (default: skipped). On uncaught exceptions, the crash modal always shows the full traceback
   including library frames, regardless of this flag. |
@@ -912,9 +1027,14 @@ On Windows, it uses `%APPDATA%\tdb\`.
 
 | File | Contents |
 |------|----------|
-| `config.json` | User preferences (keybinding scheme, color theme, step mode) |
+| `config.json` | User preferences (keybinding scheme, color theme, step mode, adapter overrides) |
 | `breakpoints.json` | Breakpoints from previous sessions, keyed by project directory |
 
+Adapter-related keys in `config.json`: `adapters` maps an adapter id to an
+executable path (`{"adapters": {"lldb-dap": "/opt/llvm/bin/lldb-dap"}}`), and
+`default_adapters` picks a language's default adapter
+(`{"default_adapters": {"cpp": "lldb-dap"}}`).
+
 Breakpoints are saved on exit and restored when debugging a program in the same
 directory. Each project's breakpoints are independent.
 
@@ -934,7 +1054,8 @@ fires as expected.
 ## Tech Stack
 
 - [textual](https://github.com/Textualize/textual) : TUI framework
-- [debugpy](https://github.com/microsoft/debugpy) : Debug Adapter Protocol implementation
+- [debugpy](https://github.com/microsoft/debugpy) : Debug Adapter Protocol implementation for Python
+- [gdb](https://sourceware.org/gdb/) / [lldb-dap](https://lldb.llvm.org/resources/lldbdap.html) : optional, user-installed DAP adapters for C/C++
 - [pygments](https://pygments.org/) : Syntax highlighting
 - [FastAPI](https://fastapi.tiangolo.com/) + [uvicorn](https://www.uvicorn.org/) : JSON-RPC server
 

{textual_debugger-0.1.5/src/tdb → textual_debugger-0.2.0}/README.md

@@ -1,12 +1,18 @@
 # `textual-debugger`
 
 `textual-debugger` (the package) provides `tdb` (the command-line tool and module),
-a full-featured terminal-based Python debugger.
-
-`tdb` is built with [textual](https://github.com/Textualize/textual)
-and [debugpy](https://github.com/microsoft/debugpy) (the Debug Adapter Protocol engine behind
-VS Code's Python debugger). It provides a rich interactive interface for stepping through code,
-inspecting variables, managing breakpoints, and evaluating expressions in complex Python programs.
+a full-featured terminal-based debugger for Python and other languages
+with a Debug Adapter Protocol (DAP) implementation. C and C++ support (via
+`gdb` or `lldb-dap`) is built in.
+
+`tdb` is built with [textual](https://github.com/Textualize/textual) and speaks
+DAP to a pluggable debug adapter: [debugpy](https://github.com/microsoft/debugpy)
+(the engine behind VS Code's Python debugger) for Python,
+[GDB's DAP mode](https://sourceware.org/gdb/current/onlinedocs/gdb.html/Debugger-Adapter-Protocol.html) or
+[lldb-dap](https://lldb.llvm.org/resources/lldbdap.html)
+for compiled code. It provides a rich interactive interface for stepping through
+code, inspecting variables, managing breakpoints, and evaluating expressions in
+complex programs.
 
 - PyPI: https://pypi.org/project/textual-debugger/
 - GitHub: https://github.com/AlDanial/tdb
@@ -17,6 +23,10 @@ MIT License.  Copyright 2026 by Al Danial.
 
 `tdb`:
 
+- debugs multiple languages through the Debug Adapter Protocol: Python (via `debugpy`,
+the richest feature set) and C/C++ (via `gdb -i dap` or `lldb-dap`), with the language
+auto-detected from the target (ref. [Multi-Language Debugging](#multi-language-debugging)).
+
 - supports debugging of synchronous, asynchronous, multi-threaded, and multi-process Python code.
 It specifically supports modules
     - `asyncio` (with a built-in async task inspector and task wait graph)
@@ -103,6 +113,16 @@ tdb my_program.py
 # debug with arguments
 tdb my_program.py arg1 arg2
 
+# debug a C/C++ (or other native) executable built with -g.  The ELF/Mach-O/PE
+# binary is auto-detected and debugged through GDB's DAP mode (GDB >= 14)
+tdb ./myprog arg1 arg2
+
+# same, but using lldb-dap (LLVM >= 17) instead of gdb
+tdb --adapter lldb-dap ./myprog
+
+# force the language when auto-detection can't tell (e.g. an extensionless script)
+tdb --lang python ./mytool
+
 # add breakpoints at lines 20 and 35 of `my_program.py` and line 14
 # of `module.py` (when -k is given, --no-stop-on-entry is set and the
 # program runs to the first breakpoint)
@@ -144,6 +164,79 @@ Alternatively, use the module entry point:
 python -m tdb my_program.py
 ```
 
+## Multi-Language Debugging
+
+`tdb` debugs any language that has a Debug Adapter Protocol backend. Two
+languages are supported out of the box:
+
+| Language | Adapter(s) | How to get the adapter | Feature level |
+|----------|------------|------------------------|---------------|
+| Python | `debugpy` (default) | installed with `textual-debugger` | everything in this README |
+| C / C++ (any native binary) | `gdb` (default), `lldb-dap` (alternate) | `gdb -i dap` requires GDB ≥ 14; `lldb-dap` ships with LLVM ≥ 17 (e.g. `apt install lldb`) | core debugging: breakpoints, stepping, stack, variables, evaluate console |
+
+### Language detection and selection
+
+The language is auto-detected from the debug target:
+
+1. File extension: `.py` → Python.
+2. Native executables (ELF, Mach-O, PE magic bytes) → C/C++.
+3. A `#!...python` shebang → Python.
+4. C/C++/Rust *source* files (`.c`, `.cpp`, `.rs`, …) produce an error with a
+   hint: compile with debug info (`g++ -g -O0`) and debug the binary.
+5. Anything else produces an error naming the `--lang` override.
+
+`--lang` forces the language; `--adapter` picks a non-default adapter within
+it (`tdb --lang cpp --adapter lldb-dap ./myprog`).
+
+> **Migration note:** extensionless Python scripts without a `python` shebang
+> were previously assumed to be Python; they now require `--lang python`.
+
+### Adapters are found on `PATH`
+
+`tdb` does not download or bundle adapters. If the adapter executable isn't
+found, the error names the package to install. To use an adapter from a
+non-standard location, or change a language's default adapter, add to
+`config.json` (see [Configuration](#configuration)):
+
+```json
+{
+  "adapters": {"lldb-dap": "/opt/llvm/bin/lldb-dap"},
+  "default_adapters": {"cpp": "lldb-dap"}
+}
+```
+
+### What works for non-Python languages
+
+Core debugging works identically for every language: breakpoints (incl.
+conditions and persistence), stepping, continue/pause, run-to-cursor, stack
+navigation, variable inspection, the evaluate console, syntax highlighting,
+and the JSON-RPC / MCP programmatic modes.
+
+Python-specific features are hidden or return a clear "not supported for this
+language" message when debugging other languages: statement-granularity
+stepping (non-Python languages always step per line), the async task /
+process inspectors and wait graph, the evaluate console's trailing-`?` help,
+remote attach (`-r`), `--python`/`--pv`, `--no-subprocess`,
+automatic child-process attachment, and the post-mortem / `tdb.breakpoint()`
+hooks (those hooks live inside Python programs by nature). `--terminal` is
+currently ignored for non-Python targets.
+
+### C/C++ tips
+
+- Compile with `-g` (ideally `-g -O0`). If no breakpoint in a file can be
+  bound, `tdb` prints a console warning suggesting the program may lack
+  debug info.
+- Stack frames pointing into system libraries often have no source on disk;
+  the Code View shows a `<Could not read …>` placeholder while the stack,
+  variables, and evaluate console remain fully usable.
+- GDB (the default adapter) has the most complete libstdc++
+  pretty-printing. `lldb-dap` (via `--adapter lldb-dap`) also debugs
+  GCC-built binaries fine — DWARF is compiler-neutral.
+- **GDB evaluate-console quirk:** GDB's DAP treats REPL input as CLI
+  commands, so evaluate expressions with an explicit `print`, e.g.
+  `print x` rather than bare `x` (bare `x` collides with GDB's
+  examine-memory command). `lldb-dap` evaluates bare expressions directly.
+
 ## Layout
 
 ```
@@ -172,7 +265,7 @@ The footer shows the most relevant keybindings for the current mode.
 ### Navigation and Keybindings
 
 
-The Code View shows syntax-highlighted Python source with line numbers.
+The Code View shows syntax-highlighted source (lexer chosen per language) with line numbers.
 A cursor line (blue) tracks your position; the current execution line is highlighted in gold.
 
 **View focus shortcuts (global):**
@@ -264,6 +357,9 @@ lands on `print(results)`, not on each interior sub-line of the `gather` call. S
 stops on each physical line--useful for inspecting how a complex expression is built up.
 The choice is saved to `~/.config/tdb/config.json`.
 
+Statement mode requires a source-language model and is currently Python-only;
+other languages always step per line (the Step Mode menu says so if you try).
+
 ### Breakpoints
 
 Click the gutter in the Code View to toggle a breakpoint, or press `b` in Debug mode.
@@ -321,6 +417,15 @@ interactive evaluation of expressions in the current scope:
 
 Variable values set here are reflected in the running code.
 
+### Cut / Paste
+
+Expression for the Evaluate Console are often copied from the Code View.
+Doing this in `tdb` differs from traditional terminal behavior, because `textual` applications
+capture mouse events for their own use.
+
+Instead, hold the `Shift` key while performing your conventional cut/paste keystrokes or mouse
+operation to get the expected behavior.
+
 ### Console Output
 
 The Console View captures stdout (normal text) and stderr (red text) from the debuggee
@@ -688,7 +793,7 @@ curl -s -X POST http://127.0.0.1:8150/rpc \
 | `set_breakpoint` | `["file:line"]` or `["file:line", "condition", "hit_condition"]` | Set a breakpoint |
 | `remove_breakpoint` | `["file:line"]` | Remove a breakpoint |
 | `list_breakpoints` | `[]` | Show all breakpoints |
-| `continue` | `[]` or `[timeout_s]` | Resume execution; on timeout returns `"still running — call pause or wait again"` (success) |
+| `continue` | `[]` or `[timeout_s]` | Resume execution; on timeout returns `"still running--call pause or wait again"` (success) |
 | `next` | `[]` or `[timeout_s]` | Step over |
 | `step_in` | `[]` or `[timeout_s]` | Step into |
 | `step_out` | `[]` or `[timeout_s]` | Step out |
@@ -727,7 +832,7 @@ Each is JSON with `event`, `data`, and `timestamp` fields.
 tdb ships a Model Context Protocol (MCP) server (`tdb-mcp`) that exposes
 the debugger as a curated set of tools an AI agent can call. The MCP
 server is a third in-process consumer of the same dispatch handlers the
-TUI and the HTTP server use — so an agent gets the same lock semantics,
+TUI and the HTTP server use so an agent gets the same lock semantics,
 including the pause-during-continue bypass, and the same DAP-backed
 inspection surface.
 
@@ -766,17 +871,24 @@ client expects to launch servers.
 | Breakpoints | `set_breakpoint(spec, condition?, hit_condition?)`, `remove_breakpoint(spec)`, `list_breakpoints()` |
 | Differentiators | `threads(thread_id?)`, `tasks(task_name?)`, `processes(name_or_pid?)`, `wait_graph()` |
 
-`control` is intentionally one tool that takes an action enum — the six
+`control` is intentionally one tool that takes an action enum. The six
 underlying RPC actions share a return shape, and agents perform
 measurably better with a small surface than with one tool per action.
 `threads` / `tasks` / `processes` overload list-vs-inspect via a
 single optional argument for the same reason.
 
+`debug_launch` accepts optional `lang` and `adapter` parameters mirroring the
+CLI's `--lang`/`--adapter`; when omitted, the language is auto-detected from
+`program`, so an agent can hand it a compiled binary directly. The
+`tasks`/`processes`/`wait_graph` tools stay registered for every language but
+return a structured "not supported when debugging C/C++"-style error for
+non-Python debuggees.
+
 ### Agent flow for a long-running step
 
 ```
 agent → control(action="continue", timeout_s=30)
-mcp   → "still running — call pause or wait again"
+mcp   → "still running, call pause or wait again"
 agent → control(action="pause")        # OR: control(action="wait_for_stop", timeout_s=30)
 mcp   → "<file>:<line>"
 agent → inspect(["x", "len(buf)"])
@@ -785,7 +897,7 @@ mcp   → "x = 7\nlen(buf) = 1024"
 
 `pause` bypasses the dispatch lock so it can interrupt a `continue`
 that's still mid-flight (HTTP and MCP share the same `NO_LOCK_ACTIONS`
-policy — see `tdb/server/app.py`).
+policy; see `tdb/server/app.py`).
 
 ### Security caveat
 
@@ -794,22 +906,23 @@ execution in the debuggee process**. This is inherent to a debugger and
 not a tdb-specific concern, but MCP clients (and the humans running
 them) should apply appropriate permission models: don't auto-approve
 `inspect` against untrusted expressions, and don't expose `tdb-mcp` on
-a network — stdio transport only by design.
+a network (stdio transport only by design).
 
 ### Deferred / out of scope (v1)
 
-- SSE-style event push — `control` and `wait_for_stop` make polling
+- SSE-style event push: `control` and `wait_for_stop` make polling
   efficient enough; events would also need uneven MCP-client support.
-- HTTP / streamable-HTTP transports — would require auth (which the
+- HTTP / streamable-HTTP transports: would require auth (which the
   HTTP RPC server also currently lacks); stdio inherits the trust of
   the process that spawned it.
-- Multi-session — one debug session per MCP process.
+- Multi-session: one debug session per MCP process.
 
 ## CLI Reference
 
 ```
 usage: tdb [-h] [-v] [-r [HOST:]PORT] [--cwd CWD] [--no-stop-on-entry]
            [--no-just-my-code] [--no-subprocess] [--python PYTHON] [--pv]
+           [--lang LANGUAGE] [--adapter ADAPTER]
            [--keybindings {default,vim,emacs}]
            [--terminal {xterm,konsole,gnome-terminal,ghostty,kitty,iterm2,warp,wezterm,terminator}]
            [--local-root PATH] [--remote-root PATH]
@@ -825,8 +938,10 @@ usage: tdb [-h] [-v] [-r [HOST:]PORT] [--cwd CWD] [--no-stop-on-entry]
 | `-k`, `--breakpoint FILE:LINE|LINE` | Set a breakpoint (may be repeated). Passing `-k` implies `--no-stop-on-entry` so the program runs straight to the first breakpoint. |
 | `--no-stop-on-entry` | Do not pause at the first line (default: stop on entry; automatic when `-k` is given) |
 | `--cwd DIR` | Working directory for the debuggee |
-| `--python PATH` | Python interpreter for the debuggee |
+| `--python PATH` | Python interpreter for the debuggee (Python targets only) |
 | `--pv` | Shorthand for --python .venv/bin/python |
+| `--lang LANGUAGE` | Debuggee language (`python`, `cpp`); default: auto-detect from the target |
+| `--adapter ADAPTER` | Debug adapter within the language (e.g. `--lang cpp --adapter lldb-dap`); default: the language's standard adapter |
 | `--no-just-my-code` | Step into stdlib/site-packages code instead of skipping it
   (default: skipped). On uncaught exceptions, the crash modal always shows the full traceback
   including library frames, regardless of this flag. |
@@ -846,9 +961,14 @@ On Windows, it uses `%APPDATA%\tdb\`.
 
 | File | Contents |
 |------|----------|
-| `config.json` | User preferences (keybinding scheme, color theme, step mode) |
+| `config.json` | User preferences (keybinding scheme, color theme, step mode, adapter overrides) |
 | `breakpoints.json` | Breakpoints from previous sessions, keyed by project directory |
 
+Adapter-related keys in `config.json`: `adapters` maps an adapter id to an
+executable path (`{"adapters": {"lldb-dap": "/opt/llvm/bin/lldb-dap"}}`), and
+`default_adapters` picks a language's default adapter
+(`{"default_adapters": {"cpp": "lldb-dap"}}`).
+
 Breakpoints are saved on exit and restored when debugging a program in the same
 directory. Each project's breakpoints are independent.
 
@@ -868,7 +988,8 @@ fires as expected.
 ## Tech Stack
 
 - [textual](https://github.com/Textualize/textual) : TUI framework
-- [debugpy](https://github.com/microsoft/debugpy) : Debug Adapter Protocol implementation
+- [debugpy](https://github.com/microsoft/debugpy) : Debug Adapter Protocol implementation for Python
+- [gdb](https://sourceware.org/gdb/) / [lldb-dap](https://lldb.llvm.org/resources/lldbdap.html) : optional, user-installed DAP adapters for C/C++
 - [pygments](https://pygments.org/) : Syntax highlighting
 - [FastAPI](https://fastapi.tiangolo.com/) + [uvicorn](https://www.uvicorn.org/) : JSON-RPC server