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.

For local Whisper transcription (default, recommended)

For voice note transcription without sending audio to external APIs, install the dependencies:

macOS (Homebrew):

brew install python ffmpeg
pip install openai-whisper

Other platforms — install python3 and ffmpeg via your package manager, then:

pip install openai-whisper

Verify the install:

python3 --version
python3 -c "import whisper; print(getattr(whisper, '__version__', 'ok'))"
ffmpeg -version

The bridge starts without these and returns a clear error if transcription is requested but dependencies are missing.

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
Run local Whisper transcription on voice notes (see below)

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`	Local Whisper transcription
`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.