traceroot

Open Source Self-improving Layer for AI Agents

⭐ Help us reach more developers and grow the TraceRoot community. Star this repo!

TraceRoot

TraceRoot turns production traces into actionable feedback and evals, closing the self-improving loop 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.

Built for your coding agent

Give your coding agent read and write access to TraceRoot through an agent-native CLI. Explore traces, signals, and the home workspace; create and update detectors, datasets, evals, dashboards, and alerts—all from your coding agent.

⭐ Star the Repository

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

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.

Setting up TraceRoot

Once you have a TraceRoot instance, create a project in your dashboard and choose how to send your first trace: let your coding agent set up instrumentation through the CLI, or configure an SDK manually.

With your coding agent

Install the TraceRoot CLI and log in:

npm install -g traceroot-cli
traceroot login

Then ask your coding agent:

Use the TraceRoot CLI to set up tracing for this application.

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.

Run a minimal TypeScript example

You need Node.js and npm, a TraceRoot project API key, and an OpenAI API key. For self-hosting, replace the cloud host URL below with your instance URL.

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.

Integrations

Native SDKs

Supported frameworks and model providers

Agent Frameworks

Model Providers

Don't see your framework or provider? Request an integration.

Security & Privacy

Your data security and privacy are our top priorities. Learn more in our Security and Privacy documentation.

Community

Special thanks to pi-mono, which powers our agent runtime.

Contributing 🤝: Help with code, documentation, integrations, or runnable examples. Start with the contribution guide and unassigned beginner issues that do not need approval.

Support 💬: If you need any type of support, we're typically most responsive on our Discord channel, but feel free to email us [email protected] too!

License

TraceRoot uses Apache 2.0 for code outside directories named ee. Those directories are covered by the Enterprise License.

Star History

Contributors

⭐ Star us on GitHub to support TraceRoot!