TraceRoot

traceroot: the open-source platform that continuously improves your ai agents.

traceroot

Open source Braintrust alternative. Find the patterns in your agent's production issues. Ship verified fixes with your coding agent.

https://github.com/user-attachments/assets/2ecf21ce-93b3-41cb-8749-e02b77467357

Core Features

Turn production failures into tested improvements

Trace production runs, use detectors to evaluate behavior, and surface recurring patterns as improvement signals. Your coding agent uses the traceroot CLI to investigate those signals and make local changes, then verifies them with offline evals. After you ship, new production traces feed the next round of detection, signals, and verification—closing a continuous improvement loop.

Step	Description
Trace	See each model call, tool call, and response, with inputs, outputs, latency, and cost.
Detect	Define what good behavior looks like. Automatically flag production runs that miss the mark.
Signals	Cluster judge outputs into signals. A background coding agent investigates traces and connected GitHub code in a sandbox to suggest fixes.
Verify	Run evals against your datasets and compare versions to measure improvements and catch regressions.

⭐ Star the Repository

If you like what we’re building, give traceroot a star ⭐ to help more developers discover it.

Setting up traceroot

Send your first trace to traceroot Cloud or your own traceroot instance: run one command and let your coding agent add the instrumentation, or configure an SDK manually.

With your coding agent

Run this from the root of the repository you want to trace:

npx -y traceroot-cli@latest setup

Works with Claude Code, Codex, Cursor, OpenCode, Pi, Antigravity, and more.

The traceroot CLI signs you in through your browser (where you can create a free account), writes a project API key into your application's env file, has Claude Code or Codex add the SDK, and waits for your first trace. It needs Node.js 20.12 or later.

• Using another coding agent? Setup can write the change out as a task for it to run.
• Self-hosting? Point setup at your instance with --host (the API origin) and --auth-host (the web app origin).

See the setup guide for each step, self-hosting, and troubleshooting.

Manually with an SDK

Prefer to configure instrumentation yourself? Use the Python SDK or TypeScript SDK. The example below sends one traced model call from a TypeScript application.

You need Node.js and npm, a traceroot project API key, and an OpenAI API key. For self-hosting, replace the host URL below with your instance's API origin (for example http://localhost:8000).

1. Install the SDK in your TypeScript project:

npm install @traceroot-ai/traceroot openai

2. Set your API keys:

export TRACEROOT_API_KEY="your-project-api-key"
export TRACEROOT_HOST_URL="https://app.traceroot.ai"
export OPENAI_API_KEY="your-openai-api-key"

3. Trace an agent call. Save this as example.ts:

import OpenAI from 'openai';
import { TraceRoot, observe } from '@traceroot-ai/traceroot';

TraceRoot.initialize({ instrumentModules: { openAI: OpenAI } });
const openai = new OpenAI();

const myAgent = observe({ name: 'my_agent', type: 'agent' }, async (query: string) => {
  const response = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: query }],
  });
  return response.choices[0].message.content;
});

async function main() {
  try {
    await myAgent("What's the weather in SF?");
  } finally {
    await TraceRoot.shutdown();
  }
}

main().catch(console.error);

4. Run it with npx tsx example.ts, then open your project's Traces page to inspect the agent run. This example makes one OpenAI API call.

Getting Started With traceroot

traceroot Cloud

Create an account to get started without running the platform yourself.

Self-Hosting

With Git, Docker Compose, and Make installed, run locally:

git clone https://github.com/traceroot-ai/traceroot.git
cd traceroot
cp .env.example .env
make prod-lite

Open localhost:3000. See the self-hosting guide for configuration and deployment details.

Integrations

Native SDKs

Language	Repository
Python	traceroot-py
TypeScript	traceroot-ts

This is the beginning of the README. Read the rest at the original. Read the full README ↗