GhostTrace is an open-source tool that replays failed AI agent runs to find the bad step

A debugger for failures with no crash

As dev.to reported, a developer going by diusazzad built GhostTrace for the Hacktoberfest Open-Source AI Challenge, Week 4. The week's theme was "Ghost in the Machine". The tool is an after-the-fact investigator for AI agents, the programs that call tools and take multi-step actions on their own.

The author's starting point is that agents rarely fail with a tidy error message. They tend to fail quietly. An agent might invent a database column that does not exist, pass invalid arguments to a tool, or get stuck repeating the same reasoning and API calls while using up millions of tokens (the small chunks of text that AI services bill by). Others lose track of their own state or run out of room in the model's context window, which is the amount of text it can hold in mind at once.

When that happens, the developer is left reading huge piles of unformatted JSON logs. GhostTrace is meant to replace that slog with something structured.

How the four-stage pipeline works

The project describes a pipeline in four stages, orchestrated by Mastra, an open-source framework for agent workflows. First, it takes in raw telemetry, meaning the recorded trail of what the agent did. It builds a causal graph from that trail, a map of which event led to which. It also flags problems such as infinite loops.

Second, it hands that evidence to Google's Gemma 2 9B, an open-weight model, which does the counterfactual reasoning. "Counterfactual" simply means asking what would have happened if one step had gone differently. Third, a grounding check requires the model's explanation to cite specific event IDs from the trace, such as [evt_104]. The idea is to keep the model from inventing a diagnosis that the logs do not support.

Fourth, the tool writes a runnable test suite in Vitest, a testing tool for TypeScript code. These tests include circuit-breaker checks, which are safeguards that stop an agent after repeated failures. The aim is for the same bug to be caught before it returns to production.

What you see and what it connects to

The front end is a dashboard built with Next.js 16. Its centerpiece is a timeline, which the author calls a trace waterfall, showing token use, tool delays and where errors occurred. Beside it sit anomaly alerts, the model's hypothesis card and the generated tests.

The project says it accepts logs from Mastra, LangChain, CrewAI, AutoGen or custom runtimes, so it is not tied to one agent framework. It also supports Sentry's OpenTelemetry-based agent tracing. Around the core sit practical pieces for a shared team tool: Auth0 login, MongoDB Atlas storage, and a design meant to keep each user's incident history private to them.

The code is under the MIT license, a permissive open-source license, and a live demo runs on Render. The author lists the test suite as 18 test files with 162 passing tests and no TypeScript errors. That is a self-reported figure about the project's own code, not proof the debugger finds real faults well.

The case for keeping it open

The author makes three arguments for using open models and open tools. The first is privacy. Agent traces can contain API keys, customer data, internal instructions and database layouts, and sending them to a closed commercial service means handing that material to a third party. With open-weight models, an organization can run the analysis on its own machines.

The second is repeatability. The author says closed services can change behavior behind the scenes, while a fixed open model should give the same diagnosis tomorrow as today. The third is cost, since teams running thousands of investigations a day would otherwise pay for each one.

These are the author's arguments, and the source gives no measurements to back them. They are still sensible questions to put to any debugging tool that reads sensitive logs.

How much weight to give it

This is a community challenge entry, not a company product launch. The post lists a long set of prize categories it is aiming for, including ones tied to Gemma, Auth0, MongoDB Atlas, Sentry, Mastra and Temporal. That suggests a project built partly to show off many technologies at once.

Some claims are strong. The author says the grounding rule completely eliminates hallucinated diagnoses. Requiring citations to real event IDs should make fabricated explanations easier to catch, but the source offers no evaluation showing it removes them. Treat it as a design idea worth studying, not a proven result.