# Debug mode

**Debug** is a permanent built-in mode for evidence-first repair. It is not a renamed
Agent mode: it gives the model a stricter workflow and a deliberately smaller tool set.

## Use it

![The composer mode menu with Debug as a built-in option](/images/mode-picker-0098.png)

Choose Debug from the mode menu before describing a failure. Screenshot supplied September 17, 2026.

1. Open the mode picker in the chat composer.
2. Choose **Debug**.
3. Describe what you expected, what happened, and the shortest reproduction you know.
4. Let the agent reproduce and localise the failure before approving a fix.
5. Confirm whether the repair worked when V3Code asks. Debug mode keeps instrumentation
   until the result is verified.

The workflow is: reproduce, localise, rank plausible causes, prove or refute them, make
the minimal fix, add a guard, then report the evidence. Failed theories stay visible as
**refuted** instead of disappearing from the transcript.

## What Debug can do

Debug receives the read-only investigation tools plus approval-gated file edits,
commands, and tests. It does **not** receive delete, git-write, browser-mutation, or MCP
tools. Any delegated helper is restricted to research.

That boundary is intentional: Debug is for repairing the reported failure without
turning the session into an unrelated refactor.

## A transcript built for investigation

Debug transcripts expose the lifecycle of each operation: preparing, waiting for your
approval, running, succeeded, failed, cancelled, or skipped. Active operations,
questions, approvals, and failures remain individually visible. Completed operations
can be grouped to keep a long investigation readable.

The `v3code.chat.transcriptDensity` setting controls completed-operation grouping:

- `verbose` keeps every operation separate.
- `standard` groups adjacent successful operations of the same kind.
- `compact` groups adjacent successful operations across kinds.
- `minimal` also starts single completed cards collapsed.

This setting affects Debug transcripts only.

## Runtime evidence

In a trusted single-folder workspace, Debug can start a loopback-only evidence sink and
pin new runtime evidence to the active investigation. Each user turn creates a run
boundary so old evidence is not mistaken for a new reproduction.

If the workspace is untrusted, has multiple roots, or the sink is unavailable, Debug
continues with the normal read and test tools. It should not claim that runtime evidence
was collected when the sink did not start.

> Note:
>
> Debug mode improves the discipline and visibility of an investigation. It does not
> guarantee that every bug can be reproduced automatically; hardware, credentials,
> external services, and user-only actions may still require your help.