AgentTrace

Inspiration

Debugging agent traces and runs sucks, especially when you have multiple sub-agents going for long running tasks. When a chain of agents fails, you get logs from three different frameworks and no way to see which agent called what, or where it broke.

What it does

AgentTrace shows a multi-agent run live:

Graph of agents and tools. Edges animate calls; red on failure.
Timeline of every operation. Agent-to-agent interactions, tool calls.
Inspector with arguments, results, errors, correlation IDs, raw payload
Ask in plain English: "Why did this run fail?".

Codex and Claude Code sessions all land in the same trace. Anything we couldn't observe is marked as unavailable instead of left blank.

How we built it

TypeScript monorepo, npm workspaces, no build step (tsx runs the TS directly).

packages/protocol: the TraceEvent schema, zod validation, and the reducer that turns an event list into entities, edges, spans and metrics.
packages/collector: Fastify. POST /v1/events to ingest, WebSocket at /v1/live for the stream, REST endpoints for summary, failures, tool calls, critical path and concurrency. JSONL persistence.
packages/adapters: A2A proxy that sits between two agents on a port and forwards requests. Codex and Claude Code hook mappers that read hook JSON off stdin and POST canonical events.
apps/dashboard: React, Vite, React Flow. Custom layered graph layout, timeline built from spans, inspector, WebSocket client with reconnect.
packages/gemini: function declarations matching the collector query endpoints, plus redaction before anything is sent.

Challenges we ran into

Claude code was hiding some errors, which weren't hidden by Codex since it is open source.
Our Codex hook mapper was written against guessed field names and was wrong. Had to capture real payloads first, then write the mapper against them.

Accomplishments that we're proud of

Adding cross-channel queries (speech, text) to the Gemini i/o layer. It was a great addition to the project.
Building a tool to make the use of generative models and agentic workflows more interpretable and aligned with necessary software practices like Observability.

What we learned

Freezing the schema first was what made parallel work possible.
Filtering LLM outputs are necessary for business logic, but also necessary for a clean user experience. For e.g., making sure the model's output is in Markdown so that we can render it cleanly.

What's next for AgentTrace

Integration with more harnesses outside of just Claude Code and Codex.
Persistence across sessions
KPIs for user sessions like token attribution per agent, tool call hallucinations, etc.