What success looks like
`init` reports the selected target, writes the local config, writes the managed instruction file, and links the project into the hosted workspace if you approve in the browser.
docs
Install once. Verify in ten seconds.
Tracebase is the closed self-learning loop for coding agents — capture, index, recall, learn. It installs into the agent surface you already use, keeps a project-scoped local store by default, and adds hosted visibility on top without changing the core workflow.
One command install
Auto-detects your active agent, writes the adapter, and links into the hosted workspace if browser auth is available.
Operator-first health
`status`, `doctor`, `events`, `report` — all read the same local substrate. CI-friendly via `--json` and non-zero exit on real defects.
Audit by default
Retrieval, injection, agent-used, and outcome events stay in one chain so reuse quality can be measured instead of guessed.
Quickstart
Three commands.
Install, confirm the surface, run a health check. The browser approval step only appears when hosted linking is available — fully offline installs skip it entirely.
$npx tracebase-ai init
Detects your active agent and writes the adapter.
$npx tracebase-ai status
One-screen install snapshot.
$npx tracebase-ai doctor
Deep integrity check — exits non-zero on real defects.
What to do next
Restart the target agent, confirm `tracebase` appears in the MCP surface, then run `status` from the project root.
Agent adapters
One install. Three agent surfaces.
`init` auto-detects the agent you are running inside. On a cold terminal it configures every locally-installed agent. You never need `--agent` under normal use.
Claude Code
.mcp.json + CLAUDE.md
- 1Run
npx tracebase-ai initin your project directory.initauto-detects Claude Code 2.x and writes.mcp.jsonso the runtime is picked up on next launch. - 2Older installs that wrote into
.claude/settings.jsonare migrated automatically — nothing to clean by hand. - 3Restart Claude Code so the MCP server boots.
- 4Run
/toolsand confirmget_reasoning_patternsis listed.
Cursor
~/.cursor/mcp.json + AGENTS.md
- 1Run
npx tracebase-ai init— if Cursor is installed locally, the adapter is written without prompting. - 2Restart Cursor so MCP reloads.
- 3Open Cursor Settings → MCP and confirm
tracebaseshows a green indicator.
Codex
codex mcp registry + AGENTS.md
- 1Run
npx tracebase-ai init— if thecodexCLI is on PATH, Codex is detected and the MCP server is registered. - 2Start a fresh Codex session in the project.
- 3Run
codex mcp listand confirmtracebaseis present.
Operate
Verify the install in ten seconds.
After install you should not have to guess. The local CLI gives you enough signal to tell a fresh project from a broken one — and enough detail to debug adapter wiring without opening the database by hand.
$npx tracebase-ai status
One-screen install snapshot. Resolved project root, active agent, local store path, install surfaces, recent event counts.
$npx tracebase-ai doctor
Deep integrity check. Fails on broken config, malformed JSON, missing MCP registration, or any real install defect.
$npx tracebase-ai events --limit 20
Read the most recent retrieval, injection, agent_used, and outcome events from the local event log.
$npx tracebase-ai report
Aggregated reuse metrics from the same substrate the hosted dashboard reads.
Lifecycle
Remove or reset cleanly.
Tracebase has a proper uninstall path. Use it to put a project back into a known-clean state before a reinstall, or for local testing.
$npx tracebase-ai remove
Removes `.tracebase/`, the managed instruction block, and the MCP entry. User content outside the managed block is preserved.
Safe cleanup
Removes only Tracebase-owned surfaces. Nothing outside the managed instruction block is touched.
Reinstall loop
For a full reset: `npx tracebase-ai remove` → `npx tracebase-ai init`.
Control plane
The dashboard reads the same event log.
The hosted dashboard is not a separate truth source. It is the visibility layer on top of the same retrieval and outcome events the CLI reads — nothing is reinterpreted between layers.
Retrieval
Candidates surfaced for the run, including shadow retrieval when enabled.
Injection
What actually entered the prompt after gating. Prompt payload and analytics stay one-to-one.
Agent used
What the agent actually used, intersected with what was truly injected — attribution stays honest.
Outcome
Whether the run resolved, and whether it was a control run. Closes the calibration loop.
Architecture
The closed self-learning loop.
Four phases. One feedback loop. Capture happens at the end of a run; learn closes back to capture. The whole loop runs locally against your project unless you opt into hosted visibility.
01Capture
Resolved runs land in a local SQLite event log — tool chain, files touched, verdict.
02Index
Traces are distilled into reusable patterns. Indexed in the same project-scoped store.
03Recall
When the next run rhymes with an indexed shape, the pattern is surfaced before re-derivation.
04Learn
Outcome attribution feeds back. Useful patterns rise; disproved ones quietly demote.
Capabilities
Five arms, one memory.
Each capability catches a specific failure mode agents hit at runtime. Same vocabulary as the landing — recall, gist, loop, guard, fold — implemented over a single project-scoped store.
01Recall
Surfaces past solutions when a similar problem returns. Vector + heuristic match against the project-scoped pattern store.
02Gist
Semantic file memory. Recalls what a file means without re-reading the bytes. Survives window compaction.
03Loop
Catches doom-loops mid-run on a six-turn rolling window. Suggests a redirect — never overrides agent judgement.
04Guard
Spots repeat tool calls and redundant fetches before they compound on the bill.
05Fold
Folds older turns into gist summaries so long horizons stay coherent without thrashing the window.
Reference
CLI reference.
The commands that matter for rollout, operations, debugging, and analytics. The public surface is intentionally small and composable — every command emits machine-readable output behind `--json`.
$npx tracebase-ai init
Initialise the local store, auto-detect the active agent (or every locally-installed agent on a cold terminal), write the adapter surfaces, and link into the hosted workspace if browser auth is available.
$npx tracebase-ai init --agent cursor
Scripting escape hatch. Restrict the install to a single adapter. Most users never need this.
$npx tracebase-ai remove
Removes `.tracebase/`, the managed instruction block, and the registered MCP entry for the active adapter. User content outside the managed block is preserved.
$npx tracebase-ai status --json
Machine-readable install snapshot. Same shape the dashboard uses.
$npx tracebase-ai doctor --json
Machine-readable health report. Non-zero exit when install integrity is broken — wire into CI for rollout gates.
$npx tracebase-ai report --json
Structured aggregated reuse analytics. Pair with `--limit` and `--after` for windowed reads.
$npx tracebase-ai recall <shape>
Look up resolved patterns for a problem shape directly from the project-scoped store. Useful for inspecting what the agent would have surfaced.
$npx tracebase-ai impact
30-day reuse + saved-tokens funnel — same fold as the hosted impact page, computed locally from the event log.
Troubleshooting
When things go wrong.
Most install problems are one of four things: wrong adapter, broken local config, missing CLI surface, or the user checking the wrong project root. Verify the specific failure first — don't edit files blind.
Install targeted the wrong agent
`init` auto-detects the agent you're running inside. To pin it explicitly, re-run with `npx tracebase-ai init --agent cursor` (or `--agent codex`). Auto-selection never picks Codex unless the `codex` CLI is actually on PATH.
`status` works in the root but not from a subdirectory
Fixed in v0.8. `status`, `doctor`, `events`, and `report` walk up to the real project root and never invent phantom nested stores.
Codex adapter says CLI is unavailable
Install the Codex CLI or use another adapter. Tracebase now surfaces this as an incomplete install instead of silently succeeding.
Need a clean reinstall
Run `npx tracebase-ai remove`, then `npx tracebase-ai init`. Removes the local store + managed integration surfaces without touching unrelated user content.