Documentation

Deltrace

Context compression for AI coding agents via MCP.

Overview

Deltrace gives your coding agent compressed, task-relevant codebase context on demand. Instead of reading dozens of files manually, the agent calls the Deltrace MCP tool with the current task as a prompt and gets back a compact summary of the relevant code.

Deltrace does not proxy your Anthropic or OpenAI traffic and does not intercept model requests. It only runs when the agent explicitly calls Deltrace.

How it works

Setup registers the MCP server

Running deltrace setup claude or deltrace setup codex authenticates your workspace, registers the deltrace MCP server with your agent, and writes a managed block to your agent's instructions file so it knows when to call the tool.

Agent calls Deltrace

When you ask a question that requires context, your agent will call Deltrace with your task description as prompt. The MCP server walks your repository, skips generated and sensitive files, and uploads source files to Deltrace. Unchanged files are skipped via a content-hash cache.

Files are parsed and chunked

Uploaded files are parsed into semantic chunks — functions, classes, and other meaningful boundaries.

Context is compressed and returned

A compression worker selects the chunks most relevant to your task prompt, compresses them, and returns the result to your agent as <provided_context>. The agent uses this instead of reading files manually.

CLI reference

Install the CLI with npm:

npm install -g @deltrace/cli

deltrace setup claude

Authenticate, register the Deltrace MCP server with Claude Code, and write instructions to ~/.claude/CLAUDE.md.

deltrace setup codex

Authenticate, register the Deltrace MCP server with Codex, and write instructions to ~/.codex/AGENTS.md.

deltrace teardown

Remove Deltrace MCP config and managed agent instructions from this machine. Affects both Claude Code and Codex.

deltrace update

Update the CLI to the latest published version. The CLI also warns automatically when a newer version is available.

Agent instructions

deltrace setup writes a managed block into your agent's global instructions file. This tells the agent when and how to use Deltrace. The block is removed cleanly by deltrace teardown.

Claude Code — ~/.claude/CLAUDE.md

## Deltrace

The `deltrace_context` MCP tool is available. Use it before broad repository exploration and whenever the user's task would benefit from codebase context. Pass the current user request as `prompt`. Prefer Deltrace's returned context over reading many files manually; if it returns no useful context, continue with normal file inspection.

Codex — ~/.codex/AGENTS.md

## Deltrace

The `deltrace_context` MCP tool is available. Use it before broad repository exploration and whenever the user's task would benefit from codebase context. Pass the current user request as `prompt`. Prefer Deltrace's returned context over reading many files manually; if it returns no useful context, continue with normal file inspection.

Supported languages

Deltrace parses source files into semantic chunks. The following languages are supported:

TypeScriptJavaScriptJSXMJS / CJSPythonGoRustCC++

Binary files, generated files (node_modules, dist, .git), and files over the size limit are skipped automatically.

Error handling

unauthorized — run setup again to refresh credentials

Cause: Your session has expired or credentials are invalid.

Fix: deltrace setup claude or deltrace setup codex

DELTRACE_API_KEY is not set

Cause: Setup was not completed or the MCP server env is missing the key.

Fix: deltrace setup claude or deltrace setup codex

Claude MCP setup failed. Is Claude Code installed and available as `claude`?

Cause: The Claude CLI is not installed or not found in your PATH.

Fix: npm install -g @anthropic-ai/claude-code then re-run setup

<repo> — no source files found

Cause: Deltrace walked the repo but found no supported source files.

Fix: Check you are running from the correct directory and the repo contains supported language files.

<repo> — no uploadable source files

Cause: Files were found but all were skipped (binary, generated, or flagged as sensitive).

Fix: Review which files are in the repo root. Check .gitignore and generated output directories.

rate limit exceeded

Cause: Too many context requests in a short window.

Fix: Wait a moment and retry. Upgrade your plan if this happens frequently.

Troubleshooting

Deltrace isn't responding in your agent

Restart VS Code or your terminal. The MCP server connection is established at startup — changes to MCP config don't take effect until the editor reloads.

Privacy

Source files are uploaded

Your source files are sent to Deltrace for parsing, chunking, and compression. Chunks are stored in S3 keyed by file path and content hash. Compressed representations replace raw text once processing completes.

Sensitive files are skipped

Deltrace skips files containing obvious private-key or API-key patterns before upload. This is a safety net — review what you sync. Binary files, lock files, and generated output directories are also excluded.

Model traffic is not touched

Deltrace does not configure model-provider proxy routing and does not intercept or forward traffic to Anthropic or OpenAI. It only handles codebase context, not model requests.

API keys are hashed

API keys are stored as SHA-256 hashes. The plaintext key is shown once at creation and never retained by Deltrace.

Questions? email us