VS Code Extension

FEATURES

The ACP VS Code Extension provides a forensic debugging environment for agent traces. It reads strictly from recorded artifacts—no re-execution occurs.

→

Timeline Visualization

A forensic view of execution history with phase indicators, status markers, and authoritative step ordering.

→

State Inspector

Detailed view of inputs, outputs, memory snapshots, and logs at any specific step.

→

Diff Viewer

Compare state changes between consecutive steps using VS Code's native diff editor.

→

Run Comparison

Audit changes between two distinct runs, aligned by step index and phase.

→

Diagnosis Reports

Evidence-based analysis of failures with specific step ID references.

VS Code Extension

TIMELINE VIEW

The timeline provides an authoritative sequence of agent execution. Each step displays:

Phase Indicators

[REASON]LLM calls
[TOOL]Tool executions
[OBSERVE]Inputs
[MEMORY]State updates
[RETRY]Retry attempts

Status Indicators

OK— Success
ERR— Error
RETRY— Retrying

Truncation Warning

If a run exceeded trace limits (default: 1000 steps), a prominent warning is displayed. Truncated runs are marked in metadata and the timeline shows where recording stopped.

VS Code Extension

STATE INSPECTOR

Click any step in the timeline to inspect its complete state in the side panel.

Recorded Data (Immutable)

  • Input — Exact prompt or arguments
  • Output — Exact response or return value
  • Memory Snapshot — Recorded context window
  • Logs — Raw stdout/stderr captures

Derived Data (Analysis)

  • Metrics — Token counts, duration
  • Annotations — Analysis warnings
  • Diff Links — Quick access to state changes

Redaction

Sensitive keys are automatically masked by the SDK before recording. You'll see ******** for API keys, tokens, and other sensitive patterns.

VS Code Extension

DIFF VIEWER

Compare state changes between any two steps using VS Code's native diff editor.

Step-to-Step Diff

View exact insertions and deletions in prompts or memory between consecutive steps. Useful for understanding how context evolves during execution.

Run Comparison

Compare two distinct runs to identify where behavior diverged:

  • • Runs are aligned by Step Index and Phase
  • • Identifies the exact step where inputs, outputs, or decisions differed
  • • Comparison is read-only—original artifacts are never modified
VS Code Extension

COMMANDS

Access all ACP commands via the Command Palette (Ctrl+Shift+P on Windows/Linux,Cmd+Shift+P on macOS). Type "ACP" to filter and see all available commands.

ACP: Open Agent Run

The primary entry point for debugging. Opens a file picker to select a run_<uuid> directory from your traces/ folder. Once loaded, the Timeline View opens automatically, displaying all recorded steps in chronological order.

How to use: Run the command → Navigate to your traces folder → Select the run directory (e.g., run_a1b2c3d4) → Click "Open"

ACP: Open at First Failure

Instantly jump to the first step where something went wrong. This command scans the loaded trace for the first step with status: "error" and automatically selects it in the Timeline, opening the State Inspector with full details about what failed.

Use case: Your agent run failed after 50 steps. Instead of scrolling through the timeline manually, this command takes you directly to the problematic step so you can inspect the exact input that caused the failure and the error message returned.

ACP: Compare With Another Run

Side-by-side comparison of two different agent runs. After selecting a second run directory, ACP aligns both traces by step index and phase, highlighting exactly where the executions diverged—whether in LLM responses, tool outputs, or memory state.

Use case: You ran the same agent twice with different seeds or prompts. Use this to identify the exact step where behavior started to differ—maybe the LLM made a different tool choice, or a tool returned different results.

Aligned by:
  • • Step Index
  • • Phase Type
  • • Tool Name (if applicable)
Highlights:
  • • Input differences
  • • Output differences
  • • Memory state changes
ACP: Generate Diagnosis Report

Creates a standalone HTML report summarizing the agent run with all detected issues, warnings, and anomalies. The report is self-contained and can be shared with team members or attached to bug reports without requiring them to have ACP installed.

Report includes: Run metadata, execution timeline visualization, flagged issues with step references, memory growth charts, tool call statistics, and error summaries.

Output formats:HTML (interactive) •PDF (printable) •Markdown (for docs)
ACP: Run Counterfactual Simulation

Advanced debugging feature that lets you create a "what-if" branch from any step in the trace. You can modify the input or output of a specific step and see how the rest of the execution would have proceeded based on the recorded data.

Example: At step 7, your agent called search("restaurants nearby"). You can create a counterfactual where the search returned different results, then observe how subsequent LLM reasoning and tool calls would have changed.

⚠️ Important: Counterfactual simulation is read-only and never modifies original traces. Simulated branches are stored separately and clearly marked as non-authoritative.

Additional Commands

ACP: Jump to StepEnter a step number to instantly navigate to that step in the timeline. Useful for large traces with 100+ steps.
ACP: Filter by PhaseShow only steps of a specific phase (REASON, TOOL, OBSERVE, etc.). Helps focus on specific aspects of agent behavior.
ACP: Export Current ViewExport the currently visible timeline and inspector state as JSON for external analysis or scripting.
ACP: Show Run SummaryDisplay a quick overview panel with run statistics: total steps, duration, error count, tool usage breakdown.
ACP: Copy Step as JSONCopy the currently selected step's full data (input, output, metadata) to clipboard in JSON format.