Agentic debugging

CLion exposes its debugger to external AI agents through the integrated MCP server. With the debugger tools connected, an agent such as Claude, Codex, or Junie can drive a CLion debug session on its own: start and stop it, manage breakpoints, step through code, inspect threads and variables, and evaluate expressions.

Instead of stepping through the code yourself, you describe the problem in natural language and let the agent collect the runtime evidence. This helps you locate issues that are hard to spot from the source code and logs alone, such as an incorrect value that appears only at run time.

Enable the Debugger MCP Toolset plugin

This functionality relies on the Debugger MCP Toolset plugin, which is bundled and enabled in CLion by default. If the relevant features are not available, make sure that you did not disable the plugin.

Press Ctrl+Alt+S to open settings and then select Plugins.
Open the Installed tab, find the Debugger MCP Toolset plugin, and select the checkbox next to the plugin name.

How the debugger reaches agents

CLion provides the debugger functions to agents in two ways:

Shared MCP server: The debugger tools are served over the MCP server together with the analysis, formatting, and other IDE tools. Their descriptions are part of the agent context at all times, even when you do not debug. The debugger tools are prefixed with xdebug_. This option is available in CLion 2026.1.3 and later.
Router mode: The MCP server exposes one universal tool, execute_tool, together with the clion-debugger skill. The commands, parameters, and debugging scenarios live in the skill, and the agent loads them only when it needs the debugger. Because the debugger descriptions stay out of the agent context until then, router mode lowers token consumption. Router mode works with the GDB, LLDB, and DAP-based debuggers and is used by agents such as Claude Code and Codex. This option is available in CLion 2026.2 and later.

Connect an agent to the debugger

The debugger tools are served over the CLion MCP server, so a client gains access to them as soon as the server is enabled.

Enable the MCP server and set up your client as described in MCP Server.
Restart the client so that it picks up the CLion tools, including the debugger tools prefixed with xdebug_.

You can review the exposed tools and turn individual tools on or off in the MCP Server settings.

Turn on router mode

In router mode, CLion keeps the debugger command descriptions out of the agent context until the agent needs them. The MCP server exposes one universal tool, execute_tool, and the agent loads the clion-debugger skill on demand. Router mode suits longer sessions, where the always-on tool descriptions take up context that the agent could spend on the task.

In the main menu, go to Settings | Tools | MCP Server | Exposed Tools.
Select the Enable router-only mode checkbox. The debugger tools stay reachable through execute_tool, and the clion-debugger skill tells the agent when to use them. To turn router mode off, clear the checkbox.

To load the skill for a debugging task, invoke it from the agent:

In Claude Code, enter /clion-debugger.
In Codex, enter $clion-debugger.

The skill provides the commands to run the program, step through it, view its state, and step into functions, so the agent loads them only for the debugging task.

What an agent can do

Through the debugger tools, an agent runs the same runtime investigation that you would perform manually:

Start a debug session for a run configuration or a source location, and check the status of running sessions (xdebug_start_debugger_session, xdebug_get_debugger_status).
List, set, and remove breakpoints, and run to a specific line (xdebug_list_breakpoints, xdebug_set_breakpoint, xdebug_remove_breakpoint, xdebug_run_to_line).
Control execution by stepping, resuming, pausing, or stopping the session (xdebug_control_session).
Read local variables, frame values, and nested fields, and evaluate or change expressions (xdebug_get_frame_values, xdebug_get_value_by_path, xdebug_evaluate_expression, xdebug_set_variable).
Inspect threads and their call stacks (xdebug_get_threads, xdebug_get_stack).

Debug your code with an agent

Open your project, then describe the problem to the agent and ask it to debug the code. For example:

The cart total is far too low. Start a debug session,
set a breakpoint in line_total(), and find out why the
discount is applied incorrectly.
        

The agent sets the breakpoints it needs, starts the debug session, and waits for the program to pause. When execution stops, it reads the call stack, the local variables, and the expressions it needs to test its hypothesis, and then reports what it finds.

CLion paused at a breakpoint in line_total(), with the Debug tool window showing the call stack and the gross and net variable values

The agent controls the standard CLion debugger, so you can follow the session in the Debug tool window and take over at any point.

Limitations

Breakpoint errors and the output of logging breakpoints are reported only by JVM-based debuggers. With the C and C++ debugger, these event streams can stay empty even when a logging breakpoint is configured.
Evaluating constexpr expressions during a debug session is not yet supported through the debugger tools.

22 July 2026