Secure, local-first trace capture and inspection for Codex and Claude agent sessions.

Install | What You Can Answer | Privacy | MCP | Development | License

Tracebase imports local agent transcripts, encrypts raw events at rest, builds a searchable local index, and serves a localhost dashboard for debugging what happened in an agent run. It is designed for developer workstations: no network interception, no hidden reasoning capture, and no remote service required.

Most LLM observability tools start from application SDKs, hosted gateways, or OpenTelemetry pipelines. Tracebase starts from the local coding-agent logs developers already have, then turns those runs into auditable engineering traces: what happened, what failed, what recovered, what got expensive, and what is safe to share.

Tracebase makes agent work inspectable after the fact. Use it to answer:

Context-waste detection is intentionally practical rather than mystical: it catches repeated searches, repeated commands, large outputs, and other patterns that burn context without clearly moving the task forward. Some expensive actions are still necessary, such as real UI automation or final release logs; the scorecard is meant to make that tradeoff visible.

npm install -g tracebase-local
tracebase init
tracebase import
tracebase serve

Open http://127.0.0.1:18427.

The npm package is tracebase-local; it installs tracebase, traces, tcodex, and tclaude.

Tracebase records transcript-visible prompts, assistant messages, exposed reasoning summaries, tool calls, tool results, cwd, timestamps, approvals/errors when present, and raw provider transcript events. It does not capture hidden/private model chain-of-thought unless a provider explicitly emits that data.

To delete local Tracebase data:

tracebase watch-uninstall
rm -rf ~/.traces

Set TRACE_KEY to a base64-encoded 32-byte key only when you need to manage encryption externally.

tracebase doctor reports paths, capture coverage, watcher state, and Codex/Claude CLI availability. Run tracebase --help for full options.

tracebase serve runs a read-only localhost dashboard. tracebase agent serves the same UI with local intake enabled.

State-changing browser requests reject Origin headers that do not exactly match the Tracebase server origin. CLI and curl requests without an Origin header remain supported. For summaries, browser-supplied command overrides are ignored; the local server invokes only allowlisted codex or claude runners.

const {
  TraceStore,
  buildExportZip,
  createServer,
  redactText
} = require("tracebase-local");

const store = new TraceStore();
store.init();
console.log(store.healthStats());

The package exports storage, server, export, summary, redaction, normalization, LLMObs, and MCP helpers.

[mcp_servers.tracebase]
command = "node"
args = ["/absolute/path/to/bin/traces.js", "mcp"]

The MCP server is read-only and exposes trace search plus canonical trace/span listing. It intentionally does not expose write tools in the OSS build.

npm install
npm test
npm audit --omit=dev

For the full local checklist, see TESTING.md.

MIT. See LICENSE.