# AetherTrace

> A local-first, open-source visual debugger, reverse proxy and replay engine for tracing and debugging multi-agent LLM workflows.

AetherTrace is an open-source, local-first workstation for debugging AI agent execution, published by ZLouada under the MIT license. It runs a reverse proxy that records LLM calls into a local SQLite database and shows them in a browser-based Flight Deck. The project is currently at v0.3.

## What It Is

AetherTrace sits between an agent application and its model provider. You point your SDK's baseURL at the local proxy (http://localhost:4000/v1), and it captures agents, models, tools, retries, HTTP requests and errors as a live execution DAG with a timeline and span inspector. It works with OpenAI, Anthropic, Ollama or local models, and is started with `npx aethertrace start`, a Docker image, or from source.

## Debugging, Breakpoints and Replay

Live breakpoints suspend matching requests so you can inspect state, mutate prompts or tool arguments, return a mock response, or abort. Runs can be forked from any span, reusing cached prefixes so unmutated ancestors cost nothing, with cache-only, safe or live replay modes (live replay requires explicit confirmation). A chaos engine can inject latency, synthetic 429 and 502 errors and malformed JSON. Circuit breakers enforce budget caps and stop repeated-request loops.

## Experiments, Evaluation and Diffing

Experiment Studio creates variants from existing traces by changing prompts, models, tool arguments or mocks, then batch-replays them. Evaluation Studio checks cost, latency, tokens, reliability and topology with structured assertions, clusters errors and exports redacted JSON or Markdown reports. Diff Arena aligns two runs semantically to show cost, latency, token and lineage differences. The CLI `assert` command can act as a CI regression gate.

## Sharing and Integrations

Runs export as portable .trace.json bundles that teammates can import into their own instance. Provenance capture records Git, dependency and environment context. OpenTelemetry OTLP/HTTP traces can be imported, and LangChain and LangGraph callback handlers plus TypeScript and Python SDKs preserve parent-child relationships. Data stays local, and secret redaction and SSRF protection are included.

## Features
- Live execution DAG and timeline with span inspector
- Drop-in reverse proxy for OpenAI-compatible calls
- Live breakpoints with prompt mutation and mock responses
- Fork and replay with cached prefixes
- Experiment Studio for variant replays
- Evaluation Studio with structured assertions
- Semantic Diff Arena
- Chaos fault injection
- Budget and loop circuit breakers
- Portable .trace.json export and import
- Secret redaction and SSRF protection
- Git and environment provenance
- CI regression gate via CLI assert
- Local SQLite (WAL) storage

## Integrations
OpenTelemetry, LangChain, LangGraph, OpenAI, Anthropic, Ollama, TypeScript SDK, Python SDK, Docker, GitHub Actions

## Platforms
CLI, WEB, DEVELOPER_SDK, API

## Pricing
Open Source

## Version
0.3.0

## Links
- Website: https://aethertrace.runs-on.dev
- Documentation: https://github.com/ZLouada/AetherTrace/tree/main/docs
- Repository: https://github.com/ZLouada/AetherTrace
- EveryDev.ai: https://www.everydev.ai/tools/aethertrace