Skip to content
V3CodeV3Code
Start here

POPULAR GUIDES

    FROM THE DOCUMENTATION

    Open this guide ↗
    ↑ ↓ select ↵ open esc closeV3Code Docs
    The editoreditor

    Debug mode

    ↗ View as Markdown

    Reproduce a bug, prove the root cause, make the smallest fix, and verify it.

    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

    Section titled “Use it”
    Choose Debug from the mode menu before describing a failure. Screenshot supplied September 17, 2026.
    The composer mode menu with Debug as a built-in option

    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

    Section titled “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

    Section titled “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

    Section titled “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.