Agent Integration (MCP Bridge)

This guide is for developers who want to use TraceGist sessions directly from a coding agent (Claude Code, Cursor, etc.).

How it works

The TraceGist extension exports session packages as ZIP files to your Downloads folder. The MCP bridge exposes those packages to your agent via the Model Context Protocol — no manual copy-paste required.

1) Install the MCP bridge

No installation needed for one-off use:

npx -y tracegist-mcp-bridge

Or install globally:

npm install -g tracegist-mcp-bridge

Requires Node.js 18 or later and a C/C++ toolchain — the bridge compiles its bundled whisper.cpp at install time. Xcode CLI tools (macOS) and build-essential (Linux) are commonly already installed; on Windows you’ll typically need to install Visual Studio Build Tools explicitly.

Voice-note transcription

Local Whisper is bundled — no Python, no system ffmpeg. The TraceGist extension records voice notes as 16 kHz mono wav, which whisper.cpp accepts directly.

Default — local Whisper (private, no external calls). Works out of the box. The default model is base.en (~150 MB), auto-downloaded on first use. Override via TRACEGIST_WHISPER_MODEL (e.g. tiny.en, small.en, large-v3).

Optional — OpenRouter (cloud, fastest first response). If you already have an OpenRouter API key for the extension’s “Analyze with AI”, forward the same key to the bridge:

{
  "mcpServers": {
    "tracegist": {
      "command": "npx",
      "args": ["-y", "tracegist-mcp-bridge"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-..."
      }
    }
  }
}

When OPENROUTER_API_KEY is set, OpenRouter is tried first and local Whisper is the fallback. The bridge logs the active path(s) at startup (Voice transcription path(s): ...).

Troubleshooting: if the first transcription fails with a “command not found” or “failed to convert audio” error, the bundled whisper.cpp didn’t compile during npm install. Install build tools and reinstall:

macOS: xcode-select --install
Debian / Ubuntu: sudo apt install build-essential
Windows: install Visual Studio Build Tools (the “Desktop development with C++” workload), then re-open your shell

On macOS 26 (Tahoe), a freshly installed Command Line Tools package may not expose the libc++ headers on the default clang++ search path, causing the whisper.cpp build to fail with fatal error: 'vector' file not found. If you hit this, set SDKROOT so clang++ finds the SDK headers:

echo 'export SDKROOT="$(xcrun --show-sdk-path)"' >> ~/.zshrc
source ~/.zshrc

Then re-run npm install (or whichever command triggers the bridge install).

2) Add to your agent config

Claude Code

Run this once in your terminal:

claude mcp add tracegist -- npx -y tracegist-mcp-bridge@latest

Claude Desktop / other agents

Add this to your claude_desktop_config.json (or equivalent MCP config for your agent):

{
  "mcpServers": {
    "tracegist": {
      "command": "npx",
      "args": ["-y", "tracegist-mcp-bridge"]
    }
  }
}

Config file locations:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Restart your agent after saving the config.

Custom package directory

By default the bridge searches ~/Downloads for TraceGist packages. Set the TRACEGIST_DIR environment variable to change this:

{
  "mcpServers": {
    "tracegist": {
      "command": "npx",
      "args": ["-y", "tracegist-mcp-bridge"],
      "env": {
        "TRACEGIST_DIR": "~/Downloads/tracegist"
      }
    }
  }
}

If you configure a custom directory, set the matching Download Subfolder in the extension settings so both sides agree on the location.

3) Export a session

In the TraceGist viewer, use Copy to Coding Agent (header) or Export Session Report (footer). The package ZIP lands in your Downloads folder (or the configured subfolder).

4) Ask your agent

Once the bridge is connected, your agent can:

List available TraceGist packages
Read the handoff markdown and manifest
Inspect network requests, interaction logs, and screenshots
Transcribe voice notes (via OpenRouter or local Whisper — see above)
Build a draft issue payload for Linear / GitHub / Jira via get_tracegist_issue_draft

Example prompt:

Read the latest TraceGist session package and summarise what went wrong.

MCP tools exposed

Tool	Description
`list_tracegist_packages`	List package ZIPs in Downloads
`get_tracegist_package_overview`	Manifest + truncated handoff preview
`get_tracegist_handoff_markdown`	Full handoff markdown
`read_tracegist_package_file`	Read any file from the ZIP (e.g. `network/api-requests.jsonl`)
`extract_tracegist_package_file`	Extract a file to disk
`transcribe_tracegist_package_voice_notes`	Voice-note transcription (OpenRouter or local Whisper)
`get_tracegist_issue_draft`	Tracker-agnostic JSON for filing a Linear / GitHub / Jira issue
`watch_live_session`	Poll real-time session events while recording is active
`get_live_screenshot`	Request and retrieve a screenshot of the current tab
`ask_tester_question`	Send a question to the tester (shown as a browser toast)
`get_tester_response`	Retrieve the tester’s voice + screenshot answer
`get_live_session_summary`	Complete interaction log and voice transcriptions after session

Live shadowing

Live shadowing lets an agent watch a recording session in real time and interact with the tester as they work.

Enable it: In the TraceGist extension settings, turn on Stream session events to MCP bridge for real-time agent collaboration. When recording starts, a startup prompt is copied to your clipboard — paste it into your agent to begin.

Workflow:

Agent calls watch_live_session every few seconds to receive console, network, error, and interaction events as they happen.
Agent calls get_live_screenshot to see what the tester is currently looking at.
Agent calls ask_tester_question to surface a question as a toast in the tester’s browser (max 200 characters).
Tester responds with a voice marker (Alt/Option + Shift + M) and/or a highlight capture (Alt/Option + Shift + S); agent retrieves the answer with get_tester_response.