Ij Debugger

IntelliJ IDEA Debugger Skill

All debugger and run-configuration tools are invoked through the universal router: execute_tool(command="<tool> --arg value ..."). Do not call the underlying handles directly.

Router argument rules:

• Every --param must be followed by a value; bare flags are not supported.
• Boolean params need an explicit true/false (e.g. --isLogStack true).
• Quote every value that contains a space or an operator — expressions almost always do. The router splits command on whitespace, so an unquoted multi-token value is misread as extra arguments and the call fails with an error like Invalid argument format: '+'. Expected '--paramName value' format. Wrap the whole value in single quotes so it stays one token:
  • --logExpression 'a.getCount() + 1' (not --logExpression a.getCount() + 1)
  • --condition 'id == 42 && name != null'
  • --expression 'user.getName().trim()'
  • If the expression itself contains single quotes (e.g. a char/String literal), wrap the outer value in double quotes instead: --logExpression "name == 'tax_rate'". Do not escape quotes with backslashes and do not JSON-encode the value.
• Omit optional params entirely instead of passing "", "/", ".", "__omit__", or other sentinels.

Goal

Use debugger evidence to answer concrete runtime questions when static code reading is not enough, or to confirm ideas from static analysis — including whether execution reaches or does not reach agent-selected code locations. Gather this evidence with minimal runtime disturbance: by default observe without stopping threads and without editing source code.

When To Use This Skill

Use this skill when at least one holds:

• a runtime value or control-flow fact is needed (actual values, branch taken, call order, thread context, or whether execution reaches a chosen location) and it cannot be derived confidently from source/logs;
• finding the relevant path would otherwise require reading many files or tracing a long call chain manually;
• the user explicitly asks to use the debugger (breakpoints, logpoints, stepping, inspect values, debugger session).

Manual activation by the user means launch and use the debugger when tools are available — do not reduce it to a conceptual discussion. Do not treat domain identifiers named debug/debugger in the user's own code as a debugger request; reason about what the user actually means.

Activation Gate (tool availability)

Use this skill only when the debugger router tools are available. Minimum required set (each invoked via execute_tool):

• xdebug_set_breakpoint (important: sets logpoints, via --logExpression)
• xdebug_start_debugger_session
• xdebug_control_session
• xdebug_get_stack
• at least one value tool: xdebug_get_frame_values, xdebug_get_value_by_path, or xdebug_evaluate_expression
• get_run_configurations

If the minimum set is unavailable: state the blocker explicitly, do not force a debugger workflow, and switch to the best fallback. Run execute_tool(command="<tool> --help") to inspect a tool's exact current contract.

Principle: Logpoint-First Debugging

Logpoints are the primary way to communicate with the IntelliJ debugger. A logpoint is a non-suspending breakpoint that does not stop execution: when the line is reached it evaluates an expression and logs the result. Reach for a logpoint first for almost every runtime question; treat suspending breakpoints, stepping, and expression evaluation as escalations you must justify, not as the default. Logpoints give runtime evidence without freezing threads — which matters for concurrent code, long-running services, flaky/timing-sensitive tests, and multi-agent workflows.

Logpoint output is dumped to debugger events, and you read it back from there. Each logpoint hit is captured as an event in the debug session's event buffer — not printed to your console and not written to any file. You collect that output by draining events: execute_tool(command="xdebug_control_session --action DRAIN_EVENTS") returns the accumulated logpoint output in tracepointOutputsTail. So the logpoint loop is: install logpoint(s) → run the scenario → drain events → map each event back to source. Reading events is the normal, expected way to get logpoint results; if you find yourself wanting to write a file or add a print statement to capture output, drain events instead.

Prefer the least disruptive tool that answers the question, in this priority order:

1. Non-suspending logpoints — execute_tool(command="xdebug_set_breakpoint --filePath <p> --line <n> --logExpression '<expr>' --suspendPolicy NONE"). A logpoint is just xdebug_set_breakpoint with a --logExpression; add --suspendPolicy NONE so it does not stop execution. Providing the --logExpression is the most important thing you do. Use for runtime values, branch evidence, counts, identifiers, and path/reachability confirmation. This is the default first probe.
2. Logpoints with condition / stack-trace logging — add --condition '<expr>' to filter, and --isLogStack true for a call path. Use when events are too frequent, only specific cases matter, or a call path is needed.
3. Thread / stack inspection of a suspended session — execute_tool(command="xdebug_get_threads") + execute_tool(command="xdebug_get_stack ..."). These read a paused session: if the program is running, suspend it first with execute_tool(command="xdebug_control_session --action PAUSE"), then read threads/stack. Use for hangs, concurrency issues, deadlocks, thread-state questions, or unclear call paths.
4. Ordinary suspending breakpoints — execute_tool(command="xdebug_set_breakpoint --filePath <p> --line <n>") (the same tool without --logExpression, keeping the default --suspendPolicy ALL). Use only when you must inspect live object graphs, evaluate multiple expressions interactively, step through code, or modify state.
5. Evaluate expression / Set value — execute_tool(command="xdebug_evaluate_expression ..."), execute_tool(command="xdebug_set_variable ..."). Use only in a suspended context and only with explicit justification; these can alter what you are investigating.

Escalate down this list only when the cheaper option cannot answer the question, and say why you escalated.

Safe Logpoint Expressions (no side effects)

--logExpression and --condition are evaluated inside the running program and can change its behavior. By default restrict them to side-effect-free reads: field/local/parameter access, non-mutating getters, arithmetic, toString() on trusted values, identity/hashCode checks.

Do not use expressions that mutate state, perform I/O, advance iterators/streams, trigger side-effecting lazy initialization, or call methods with observable side effects — unless the user explicitly asked to enter a controlled mutation/debugging mode and accepted that program behavior may change.

Logpoint Placement: Variable Scope And Initialization

A logpoint evaluates its --logExpression at the moment execution reaches the line, before that line's statement runs. Every symbol the expression references must already be assigned and in scope at that point, or evaluation fails (you will see an error such as Variable 'x' has not been initialized / Cannot find local variable 'x' in breakpointErrorsTail, and no value is logged).

Rules for picking the line:

• Do not place a logpoint on the line that declares or initializes the variable you want to log, nor in the middle of a multi-line statement that assigns it. At that position the variable does not hold its value yet.
• For a multi-line assignment such as a fluent/builder chain

  List<String> configured = jdbc.sql("…")   // line 20  ← declaration starts here
      .query(String.class)                   // line 21
      .list();                               // line 22  ← assignment completes here
  this.rate = new BigDecimal(configured.get(0)); // line 23

  a logpoint on line 21 logging configured.get(0) fails — configured is assigned only after line 22. Place it on the first line after the statement's terminating ; (here line 23), where configured is initialized.
• General rule: put the logpoint on the earliest executable line where every symbol in the expression is already initialized and in scope. To capture a value at a method's entry, target the first executable line of the body, not the signature/parameter line.
• After installing, run once and read breakpointErrorsTail. If you see an uninitialized/unresolved-variable error, move the logpoint to a later line (or pick an expression whose inputs are already available) and rerun.

Initial Triage Before Debugging

Start with minimal static triage (error text, stack trace, nearby source). Start debugger work when: static analysis leaves multiple plausible runtime hypotheses; deciding between them requires concrete values or exact control flow; stepping is cheaper than reading a large cross-file path; or the user explicitly asked. Install the first logpoint(s) early and collect evidence before changing runtime behavior.

Mandatory Runtime Evidence

Before editing code for a runtime-behavior issue when debugger evidence is available, capture:

• for reachability/branch questions: logpoint output proving execution did or did not hit a chosen location (or its absence across a full reproduction);
• for state questions: at least one concrete runtime value, via a logpoint expression or — in a suspended session — xdebug_get_frame_values / xdebug_get_value_by_path / xdebug_evaluate_expression;
• when you suspend: the paused location (file/line) and the top call path via xdebug_get_stack.

Do not assert runtime conclusions before this evidence is captured unless a clear blocker is already stated.

Hypothesis-Driven Batch Logpoints

Logpoints are cheap and non-suspending, so prefer installing a batch derived from your hypotheses, then run the scenario once:

1. Form 2–5 concrete hypotheses about where/why runtime behavior diverges.
2. Install one logpoint per hypothesis anchor (branch decision, mapping boundary, state transition, dynamic dispatch, error construction, queue handoff), each logging the values that confirm or refute that hypothesis.
3. Run the scenario once via execute_tool(command="xdebug_start_debugger_session ...").
4. Read output with execute_tool(command="xdebug_control_session --action DRAIN_EVENTS") and map each line back to its source location and hypothesis.
5. Refine hypotheses or escalate to stronger tools only when logpoint evidence is insufficient.

Reproduction Mode Selection

1. AUTO: you can run/rerun the scenario directly. Use xdebug_start_debugger_session to launch with debugging, or execute_run_configuration for a non-debug run when you only need output/exit code.
2. ASSISTED: reproduction needs a user-only action (UI flow, auth, external dependency, hardware).
3. HYBRID: try AUTO once or twice, then switch to ASSISTED if it does not reproduce.

If the candidate target is a test, default to AUTO. Never ask the user to reproduce before logpoints/breakpoints are prepared.

Test Task Execution

• To debug a test: execute_tool(command="xdebug_start_debugger_session --filePath <p> --line <n>") pointing at the test method, or --configurationName <name> for an existing test run configuration. To run without debugging (e.g. confirm it fails first): execute_tool(command="execute_run_configuration ...") with the same targeting modes.
• After triggering, inspect state with execute_tool(command="xdebug_get_debugger_status") and continue inside the resulting session.
• Do not ask the user to rerun a test manually unless no available path can reproduce it or repro requires user-only setup.

Argument Hygiene

• Optional params are omitted or set to a real value; omitted means omitted.
• Never encode omitted params with placeholder strings such as "", "/", "__omit__", ".", or fake paths.
• Treat debugger IDs and paths as opaque runtime data: copy them from tool outputs, do not synthesize them.

Session Binding

• Before preparing logpoints/breakpoints or launching, call execute_tool(command="xdebug_get_debugger_status").
• If an active relevant session exists, continue inside it instead of starting another.
• Capture the exact sessionId from status/start and reuse it in all session-scoped calls (--sessionId <id>).
• If a session stops, times out, or disappears, do not reuse the old sessionId; refresh via xdebug_get_debugger_status first. After the paused location changes, re-read frameIndex/path from a fresh xdebug_get_stack.

Run Configuration Resolution

• Resolve configurationName only from execute_tool(command="get_run_configurations"); do not pass a test method name or other derived identifier.
• Use supportsDynamicLaunchOverrides from get_run_configurations as the source of truth for --programArguments, --workingDirectory, and --envs.
• Use launch overrides only when they materially improve reproducibility/observability and the run config supports them.

Breakpoint And Logpoint Ownership And Hygiene

• Start with execute_tool(command="xdebug_list_breakpoints") and treat returned owner as source of truth (user/agent). Logpoints appear here too.
• Snapshot the full baseline of each breakpoint you may touch — enabled, logExpression, condition, isLogMessage, isLogStack, suspendPolicy, and temporary (all returned by xdebug_list_breakpoints). You need this because a breakpointId-mode update rewrites the whole breakpoint (see Targeting Modes).
• Avoid broad breakpoint churn between iterations — change the minimum set needed for the next probe.
• xdebug_remove_breakpoint defaults to --owner agent; global cleanup needs two calls: --owner agent then --owner user.

Breakpoint And Logpoint Targeting Modes

xdebug_set_breakpoint (whether or not you pass --logExpression) has two mutually exclusive modes — never mix in one call:

• Location mode: pass --filePath + --line (1-based); omit --breakpointId.
• breakpointId mode: pass --breakpointId <id> (an opaque canonical id from a prior xdebug_set_*/xdebug_list_breakpoints).

breakpointId mode rewrites the whole breakpoint, it does not patch it. Treat an update as "write the full breakpoint", never "tweak one flag".

After each call, inspect the returned lineText and confirm the excerpt matches the intended line. A successful response does not prove --condition/--logExpression are valid; verify via breakpointErrorsTail / tracepointOutputsTail after the next run.