Set up TraceRoot tracing in this repo.
1. Install the CLI: npm install -g traceroot-cli
2. Sign in: traceroot login (use traceroot login --api-key <key> in CI).
3. Run traceroot instrument --agent generic --print and follow the prompt it prints to add the TraceRoot SDK (Python: pip install traceroot, TypeScript: npm install @traceroot-ai/traceroot) and initialize it once at startup.
4. Run the app once, then confirm the trace with: traceroot traces list --since 1h
5. If anything fails, run traceroot doctor and fix what it reports.
Docs: https://traceroot.ai/docs/cli/get-started
Works with
real agents. real traffic. real numbers.
Measured on live traffic across every workspace.
01 traces processed8.4M+Processed in the past 90 days, across all workspaces.
02 quality+31%Success-rate gain after the first signals are fixed.
04 cost saved$100K+Annualized, per large workflow.
What traceroot does to the agents it watches, past 90 days of production traffic.
your agent passed the tests. production found the gaps.
Agents rarely crash. They fail in three quiet ways.
01Unexpected inputs
Users ask what you never tested.
02Silent failures
It says done. It isn’t.
03Quiet drift
Every release, a little worse.
Figure 1. Three ways production finds the gaps your tests miss.
turn production failures into tested improvements.
Background coding agents investigate production signals using GitHub code in sandboxes and recommend fixes. Get alerts in Slack, then apply and verify changes with your coding agent and offline evals.
traceroot
your agentv12v13signals11 open12 opentraceroot agentreproducepatchtestevalspasstracespassflaggedtriggerverifyimprove code
Your agent's traces are judged by detectors, and flagged runs cluster into signals. The traceroot agent picks up each signal, reproduces and patches the failure in a sandbox connected to your GitHub repo, verifies the fix against your evals, and improves your agent's code.
How it works
01. Trace
See each model call, tool call, and response, with inputs, outputs, latency, and cost.
Tracecaf8d705e1c94b2a8f03d6b1a7e5c2d9
TraceTimelineDetectors
support_agent.run38.2s
anthropic.messages.create1.4s
get_order120ms
lookup_policy95ms
anthropic.messages.create2.1s
issue_refund310ms
anthropic.messages.create1.2s
send_reply80ms
update_ticket60ms
issue_refund
Span kind: toolLatency: 310ms
order A-2291policy limit $500
Input
{ order: "A-2291", amount: 840 }
Output
{ status: "refunded",
approved_by: null }
02. Detect
Define what good behavior looks like. Detectors use LLM judges to flag production runs that miss the mark.
Detectors›Failure DetectorLast 24 hours
Run
Trace
Identified
Summary
8be45604
7352f817
No
–
4297fab5
8975d50d
No
–
418109b1
caf8d705
Yes
Refunded $840; the policy limit is $500
1189a28c
6964cc49
Yes
Refunded $1,200 without manager approval
a96b7f8e
ac80a1a6
No
–
c37c8537
92d84278
No
–
958cf432
7cf8f869
No
–
dd41c2b7
5a3e90f1
No
–
2 of 8 flagged · same root cause
03. Signals
A background coding agent investigates the traces and your GitHub code in a sandbox and pinpoints the fix down to the commit, file, and line.
SignalIssues refunds above the policy limitOpen
14traces grouped
2detectors agree
Oct 14first seen
$9.6Kover the limit
Occurrences · last 7 days
PR #179 merged
Oct 12131415161718
Grouped traces 3 of 14
caf8d70538.2s$840 refund
6964cc4941.0s$1,200 refund
e41b09a229.7s$650 refund
Root cause by coding agent
PR #179 renamed refund_max; the policy lookup still reads the old key, so the limit falls back to none.
Where
support/policy.ts:12 · PR #179
Suggested change fix/refund-limit
-Read the limit from refund_max.
+Read refunds.max_amount; if missing, hold for a person.
04. Verify
Run evals against your datasets and compare versions to measure improvements and catch regressions. New production traffic starts the cycle again.
Evals›support-golden-set53 cases
Metric
main b20f09e
fix/refund-limit
Δ
Pass rate
89%
98%
+9
Cases passed
47 / 53
52 / 53
+5
Policy violations
6%
0%
−6
Refunds correct
91%
100%
+9
Latency p50
4.1s
4.0s
−0.1s
Tokens / run
21K
21K
0
Cost / run
$0.03
$0.03
0
Regressions
–
0
0 regressions · ready to merge
Built for your coding agent.
Read traces, signals, and workspace context; manage detectors, datasets, evals, dashboards, and alerts, all through an agent-native CLI. Give your coding agent the context to make changes and verify them.
claude codecodexcursoropencodepiantigravitytracesdetectorssignalsevalsdatasetsalertstraceroot
tracerootclaude codetraces
Figure 3. Coding agents stream requests through TraceRoot to the workspace surfaces they need.
Works with your stack.
Native SDKs for Python and TypeScript, auto-instrumentation for the frameworks and model providers you already use, all over OpenTelemetry.
Figure 4. Every integration is documented and links to its setup guide.
enterprise-grade security.
Built with security in mind. Your data is protected with industry-leading standards. Use TraceRoot Cloud, or self-host the full stack with Docker and decide exactly where your data goes.
Simple, transparent pricing.
Start free, no credit card needed. Bring your own model keys on every plan, or use hosted models.
TraceRoot is an open-source AI agent improvement platform built on production evidence. Trace agent runs, detect failures, investigate signals, and compare changes with evals. Bring that context to your coding agent through the TraceRoot CLI.
02How does the improvement loop work?
TraceRoot automatically detects failures and inefficiencies in production agent traffic, then clusters related judge outputs into improvement signals. Your coding agent uses the TraceRoot CLI to investigate those signals and make changes in a local worktree. Compare offline agent eval runs to verify the fix and catch regressions, then repeat the loop with new production traffic.
03How do detectors and evals work together?
Detectors run online evaluations on production traces to identify failures and inefficiencies. Patterns across judge outputs surface as improvement signals. Offline agent evals then test your changes against datasets and compare results with a baseline to verify the fix and catch regressions.
04Can I use TraceRoot with my coding agent?
Yes. The TraceRoot CLI gives your coding agent access to production traces, detectors, datasets, evals, dashboards, and alerts. Install it with npm install -g traceroot-cli, then run traceroot login. CLI setup
05Does TraceRoot work with my agent stack?
TraceRoot offers Python and JavaScript/TypeScript SDKs, OpenTelemetry-compatible tracing, and integrations with frameworks such as LangGraph, Vercel AI SDK, and CrewAI. Start by sending traces from your application, then add detectors and evals as you need them. Explore the docs
06Is TraceRoot open source? Can I self-host it?
Yes. You can use TraceRoot Cloud or self-host with Docker. Code outside directories named ee is licensed under Apache 2.0; those enterprise directories use a separate Enterprise License. Self-hosting and source code
07Can I start for free?
Yes. TraceRoot Cloud has a free plan with no credit card required. Bring your own model API keys or use hosted models. View pricing for included usage and paid plans.
index.md · text/markdown · what an agent gets
# TraceRoot – Open Source AI Agent Improvement Platform
Find the patterns in your agent's production issues. Ship verified fixes
with your coding agent. Everything here runs from the traceroot CLI;
add --json to any command for one machine-readable document on stdout
on success, or a JSON error on stderr on failure.
## Start here
npm install -g traceroot-cli # or once: npx traceroot-cli --help
traceroot login # browser sign-in, or --api-key tr_...
traceroot doctor # credentials, repo, env, skills
traceroot instrument --agent claude --print
# prompt that adds tracing to this repo## Make your coding agent TraceRoot-aware
traceroot skills list # skills and install status per agent # add tracing to an app
traceroot skills install traceroot-instrument-repo --agent claude
# one runnable trace in minutes
traceroot skills install traceroot-quickstart --agent codex
# offline evals
npx skills add traceroot-ai/traceroot-skills --skill traceroot-eval
Agents: claude (.claude/skills), codex (~/.codex/skills),
generic (.agents/skills).
## Investigate production
traceroot traces list --since 1h --limit 10
traceroot traces get <trace-id> --fields full # span tree with I/O
traceroot traces export <trace-id> --output ./out
traceroot findings list --since 24h # detector findings
traceroot findings get --trace <trace-id> # results and root cause
traceroot sql "SELECT model_name, avg(duration_ms) FROM spans
GROUP BY model_name"
## Close the loop
traceroot detectors create --from-file detector.json
traceroot alerts create --from-file rule.json
traceroot datasets versions get <version-id> # cases and source traces
traceroot evals runs list --evaluation-id <id>
traceroot evals runs get <run-id> # scores, cost, duration
Also: projects, workspaces, dashboards, widgets, sql schema. Run
traceroot <command> --help for every flag.
## Scripting
traceroot traces list --since 24h --json | jq '.data[].trace_id'
Exit codes: 0 ok · 1 internal · 2 usage · 3 auth · 4 not found ·
5 network (retry).
Env: TRACEROOT_API_KEY, TRACEROOT_HOST_URL, TRACEROOT_PROJECT_ID.
## Instrument your app
pip install traceroot # Python
npm install @traceroot-ai/traceroot # TypeScript
Then initialize it in Python:
import traceroot
from traceroot import Integration
traceroot.initialize(integrations=[Integration.OPENAI])
OpenTelemetry-based, 22 integrations:
https://traceroot.ai/docs/integrations/overview
## Trace your coding agent
claude plugin marketplace add \
traceroot-ai/traceroot-claude-code-plugin
claude plugin install \
traceroot-observability@traceroot-claude-code-plugin
codex plugin marketplace add traceroot-ai/traceroot-codex-plugin
codex plugin add tracing@traceroot-codex-plugin
pi install npm:@traceroot-ai/pi-extension
## How it works
1. Trace: model and tool calls from your agent, with inputs, outputs,
latency and cost.
2. Detect: LLM judges score production runs against what good looks like.
3. Signals: judge outputs are clustered; a background coding agent
investigates traces and GitHub code in a sandbox and pinpoints the
commit, file and line. Alerts go to Slack.
4. Verify: offline evals compare the fix with a baseline before it ships.
New production traffic starts the cycle again.
## Pricing
Free $0 · Starter $30/mo · Pro $200/mo · Enterprise custom.
Free: 2 seats, 50k events/mo, 15-day retention, 100 detector runs/mo.
BYOK or hosted LLM on every plan. https://traceroot.ai/#pricing
## Security and self-host
SOC 2 Type II, HIPAA, and ISO 27001 in progress. https://traceroot.ai/security
git clone https://github.com/traceroot-ai/traceroot.git
cd traceroot && make prod # full stack in Docker Compose
Kubernetes: traceroot-ai/traceroot-k8s (Helm chart)
AWS: traceroot-ai/traceroot-terraform-aws (experimental)
Apache-2.0 outside ee/ directories, which use the Enterprise License.
## Links
- CLI docs: https://traceroot.ai/docs/cli/get-started
- CLI source: https://github.com/traceroot-ai/traceroot-cli
- Docs index: https://traceroot.ai/docs/llms.txt
- Platform: https://github.com/traceroot-ai/traceroot
- Skills: https://github.com/traceroot-ai/traceroot-skills
- Python SDK: https://github.com/traceroot-ai/traceroot-py
- TS SDK: https://github.com/traceroot-ai/traceroot-ts
- App: https://app.traceroot.ai
What an agent (or curl) gets at /index.md: the CLI-first version of this page. /llms.txt lists every page.
opencode
