feat(tools): Terminal-Integrated Debugging Companion via Debug Adapter Protocol (DAP)

[okaditya84]

What would you like to be added?

A DAP (Debug Adapter Protocol) toolset for the Gemini CLI agent that enables
it to attach to live running processes (Node.js, Python, Go, etc.), set
breakpoints, inspect stack traces, query variable states, and perform automated
root-cause analysis i.e all directly from within the terminal session.

This introduces a new debug tool category under packages/core/src/tools/,
parallel to existing tools like run_shell_command and read_file, consisting
of the following agent-callable tools:

New tools proposed:

• debug_launch: Launch a target program under a DAP debug adapter and
  return a session handle
• debug_attach: Attach to an already-running process by PID or port
• debug_set_breakpoint: Set a breakpoint at a file + line or function name
• debug_continue: Resume execution until the next breakpoint or program end
• debug_stack_trace: Retrieve the current call stack with file, line, and
  function context
• debug_get_variables: Inspect local/global variables and their values
  at the current stack frame
• debug_evaluate: Evaluate an arbitrary expression in the current debug context
• debug_step: Step over / into / out of the current line
• debug_disconnect: Cleanly terminate the debug session

New interactive mode:

A /debug slash command that enters a persistent "Debug Mode" where the agent
maintains a live DAP session across multiple turns, allowing natural language
debugging like: "Why is user null here?" → agent inspects variables and
explains the root cause.

Language support (Phase 1):

• Node.js / TypeScript via built-in V8 inspector (--inspect flag, port 9229)
• Python via debugpy (python -m debugpy --listen 5678)
• GoLang via dlv Delve debugger (dlv debug --headless --listen :2345)

Why is this needed?

Today, when a developer encounters a bug while working with Gemini CLI, the
agent's only tool is reading source code, running the program, and guessing
from static text output. It cannot observe live runtime state i.e the actual
values of variables, the exact call stack at the moment of failure, or the
execution path that led to the crash.

This creates a fundamental gap: the hardest bugs are runtime bugs. They don't
appear in source code, they appear in memory at runtime.

The Debug Adapter Protocol (DAP) : developed by Microsoft and used by VS
Code, Neovim, and virtually every modern editor i.e is the industry-standard way
to communicate with debuggers. It is language-agnostic and already has mature
adapters for every major language. By integrating DAP into Gemini CLI's tool
system, the agent gains full visibility into running programs.

Concrete scenarios this unlocks:

1. "My Flask app crashes with a NullPointerError, figure out why" → Agent
   launches the app under debugpy, sets a breakpoint at the crash site,
   inspects the variable state, and explains exactly which input caused user
   to be None

2. "This Node.js async function returns undefined sometimes, debug it" →
   Agent attaches to the process, sets conditional breakpoints, steps through
   the async chain, and identifies the race condition

3. "My Go service panics under load i.e what's the stack trace?" → Agent
   attaches Delve, captures the panic stack trace, correlates it with the
   source, and suggests a fix

Without DAP integration, Gemini CLI is a static code analysis tool. With it,
it becomes a true debugging partner, the closest thing to JARVIS for
software development that currently exists in a terminal.

This is directly aligned with GSoC 2026 Idea #7 and the project's stated goal
of making Gemini CLI the most capable AI coding agent in the terminal.

Additional context

Relevant existing files to extend:

• packages/core/src/tools/: All new DAP tools go here as individual
  .ts files, following the same pattern as run-shell-command.ts and
  read-file.ts
• packages/core/src/tools/tool-registry.ts: DAP tools register here
  alongside existing tools
• packages/core/src/core/client.ts: Agent loop; /debug slash command
  integrates here to maintain session state across turns
• packages/cli/src/ui/: Debug mode UI: show current breakpoint location,
  variable panel, stack trace inline in the Ink TUI

DAP reference implementation:

• Protocol spec: https://microsoft.github.io/debug-adapter-protocol/
• Node.js vscode-debugadapter npm package handles the DAP wire protocol
• debugpy (Python), dlv (Go) are the target language adapters for Phase 1

Proposed package structure:
packages/core/src/tools/dap/
├── dap-client.ts # Low-level DAP session manager (connect, send, receive)
├── debug-launch.ts # debug_launch tool
├── debug-attach.ts # debug_attach tool
├── debug-set-breakpoint.ts
├── debug-stack-trace.ts
├── debug-get-variables.ts
├── debug-evaluate.ts
├── debug-step.ts
├── debug-disconnect.ts
└── types.ts # Shared DAP types (StackFrame, Variable, Breakpoint)

Security considerations:

• DAP sessions are local-only by default (localhost ports); no remote
  debugging without explicit user opt-in
• debug_evaluate is sandboxed, arbitrary expression evaluation in a
  live process is powerful and must be gated behind the existing tool
  approval system
• Debug sessions must be cleaned up on agent exit or /quit to avoid
  zombie debug adapters holding process handles

Related issues:

• None: searched DAP integration, DAP debugger, debug adapter protocol,
  breakpoint agent no relevant open issues exist

Searched queries (confirming no duplicates):

• is:issue state:open DAP integration → 0 results
• is:issue state:open debug adapter protocol → 0 results
• is:issue state:open DAP debugger → 1 unrelated result
• is:issue state:open breakpoint agent → 8 unrelated results

I am proposing this as part of my GSoC 2026 application for Gemini CLI
(Idea #7 : Terminal-Integrated Debugging Companion). I am prepared to provide
a working proof-of-concept dap-client.ts that establishes a DAP session with
a Node.js process and retrieves a stack trace, available for maintainer review
before any formal work begins.

[okaditya84]

Proof-of-concept note: I have already verified the DAP wire protocol
works with Node.js's built-in V8 inspector. Here's what a minimal
debug_stack_trace tool response looks like when attached to a running
Node.js process:

The agent sends: {"command": "stackTrace", "threadId": 1}
The adapter returns the call stack with exact file paths, line numbers,
and function names — all of which the agent can then correlate with
source code via the existing read_file tool.

This confirms the technical feasibility of the full DAP toolset proposed above.

[SUNDRAM07]

Hi everyone, I've implemented a comprehensive proof-of-concept for Idea #7: Debug Companion in Draft PR #22472.

This implementation covers 7 architectural layers with 33 modules and 9 LLM-facing debug tools. I've focused heavily on production-grade infrastructure, including:

DAP Protocol Layer: Full TCP transport with request/response correlation.
Analysis Engine: Stack trace enrichment, root cause analyzer, and fix suggestion engine (11 patterns).
Breakpoint System: Data breakpoints, exception monitoring, and pre-validation logic.
Security & Infrastructure: Policy guards, input sanitization, and adapter process management for Node.js, Python, Go, and Ruby.
The PR includes 419 passing tests (1.59s duration) and is clean under TypeScript strict mode.

I'd love to get feedback on the architecture from the mentors and @okaditya84. I'm excited about the potential for bringing native runtime debugging to Gemini CLI!

Related to #20674

[okaditya84]

@SUNDRAM07 I am an individual contributor so it won't be prudent if I reviewed your PR, however please know that this issue and the topic it deals with was pointed out by me at the first place, so kindly revert the PR and please let the maintainers review my Issue as an individual.
Moreover, you are not allowed to make draft PRs or submissions without you being assigned the issue by the maintainers. Read the contributing guidelines file.

[SUNDRAM07]

Hey @okaditya84, I appreciate you raising this feature — it's a great idea and I was genuinely excited to build on it.

Just to clarify a couple of things though: the CONTRIBUTING.md actually encourages Draft PRs for early feedback (Section 3: "Use draft PRs for work in progress"). There's no rule requiring assignment before opening a Draft — /assign is available for anyone to self-assign, and this issue currently has no assignees.

Opening an issue is great for initiating the conversation, but it doesn't create exclusive ownership over the implementation. That's the whole point of open source — multiple people can contribute ideas and code, and maintainers decide the direction.

I tagged you specifically because I wanted your input since you clearly thought deeply about this. Happy to collaborate if you're open to it. At the end of the day, the maintainers will decide which approach best serves the project.