Trace: AI Debugging Agent for VSCode

An autonomous AI agent that debugs your backend code using LSP navigation, live test feedback, and structured editing.

Multi-Model • Get Started • How It Works • FAQ • Roadmap

Supported Models

Trace works with a wide range of LLM providers, including free options:

Get Started

Install

1. Install the Trace extension from the VSCode marketplace
2. Click the Trace icon in the activity bar (left sidebar)

Configure a Model

Open VSCode Settings (Cmd+, / Ctrl+,) and search for trace.model:

• trace.model.provider — Choose: openai, deepseek, kimi, gemini, groq, ollama, or custom
• trace.model.apiKey — Your API key (not needed for Ollama)
• trace.model.modelId — Model to use (e.g., gpt-4o, deepseek-chat, gemini-2.0-flash)
• trace.model.baseUrl — Custom endpoint (auto-filled for known providers)

Quick start with a free model:

{
  "trace.model.provider": "gemini",
  "trace.model.apiKey": "YOUR_GOOGLE_AI_STUDIO_KEY",
  "trace.model.modelId": "gemini-2.0-flash"
}

Or use a local model with Ollama (no API key needed):

{
  "trace.model.provider": "ollama",
  "trace.model.modelId": "llama3.1"
}

Use Trace

1. Describe the bug in the chat input
2. (Optional) Expand "Repro Steps" to configure build and test commands — this gives the agent access to runtime feedback
3. Hit the Send button (purple arrow)
4. Watch the agent navigate your code, make edits, and verify fixes
5. Review the proposed changes and Apply or Revert

You can provide feedback to the agent while it's running — it will incorporate your input in the next step.

How It Works

Bug Description + Repro Steps
    |
    v
[Agent Loop — iterates until fixed or max iterations]
    |-- LLM generates thought + tool calls
    |-- Executes tools:
    |     |-- Navigation: ReadFile, GoToDefinition, GetAllReferences, FindTextInFiles
    |     |-- Editing: ReplaceText (match-and-replace with hallucination detection)
    |     |-- Verification: Run build + test commands, check output
    |-- Observation fed back to LLM
    |-- Repeat
    v
Proposed Fix (diff view with Apply/Revert)

Key Features

• LSP Integration — GoToDefinition, GetAllReferences, GetFileSymbols for real IDE-level code navigation
• Match-and-Replace Editing — The LLM must reproduce original code with line numbers before replacing, catching hallucinations and indentation errors
• Live Verification — Runs your actual build and test commands, giving the agent real feedback
• Backtracking — Agent can undo changes and try a different approach
• Streaming Output — See the agent's reasoning in real-time
• Diff View — Monaco-powered diff editor to review all changes before accepting

Agent Tools

Configuration Reference

Model Settings

Agent & Session Settings

Transcript export: Cmd+Shift+P → Trace: Export Session opens any recorded session as a shareable markdown transcript (thoughts, tool calls, observations, diffs, token/cost totals).

Safety: Trace warns when your working tree has uncommitted changes at session start (with a one-click stash). With approvalMode set to edits or all, the agent pauses before each mutating batch and shows an approval card in the sidebar — rejections (with your reason) are fed back so the agent adjusts instead of retrying.

Session traces & resume: Trace records each debugging session (tool calls, LLM token usage, verify results) as JSONL under .trace/sessions/ in your workspace (the directory self-gitignores). If VSCode restarts mid-session, Trace offers to resume the interrupted session on next activation.

Repro Settings

FAQ

How is Trace related to SWE-agent?

We were inspired by SWE-agent and extended their core insight around building good agent-computer interfaces. We added LSP navigation tools (GoToDefinition, GetAllReferences), embedded the agent directly in VSCode for real-time developer feedback, and implemented match-and-replace editing to reduce hallucination errors.

Why match-and-replace editing?

LLMs struggle with large edits. Our technique forces the agent to generate the original text with line numbers alongside the replacement. This catches hallucinated code (if the original doesn't match, the edit fails gracefully) and enforces correct indentation.

Why does Verify take long?

Check the output for common issues:

1. Port conflict — Kill any processes using the same port in your terminal
2. Build detection — Configure trace.repro.buildReadyText if the default patterns don't match your build output
3. Slow builds — Some projects just take time to build

Can I use free models?

Yes! Gemini 2.0 Flash (free tier), Groq (free tier), Kimi/Moonshot (free tier), and Ollama (fully local, no cost) all work with Trace. See the Supported Models table, and MODELS.md for the measured reliability matrix and how to benchmark a model yourself.

How do I customize prompts?

Edit src/config/default.yaml and rebuild the extension with npm run package.

Development

# Install dependencies
npm run install:all

# Build (development)
npm run compile

# Build (production — extension + webview)
npm run package

# Watch mode
npm run watch

# Lint
npm run lint

Roadmap

See IMPROVEMENT_PLAN.md for the full prioritized engineering backlog (session persistence, eval harness, approval gates, safety guardrails, model reliability matrix) with execution order and progress tracking.

High-level themes:

• Automated repro step creation (LLM-assisted test generation)
• Better history management (summarization, embedding-based pruning)
• Stateful file representation (avoid re-reading unchanged files)
• Improved context discovery with embeddings
• Frontend/UI bug support (beyond backend)
• Comprehensive test suite

License

MIT

If you find Trace helpful, please give the repo a star to show your support!