GhostTrace: Capture 'Phantom Branches' to Debug Rejected Decisions in AI Agents

Source: Dev.to

Overview

When an AI agent makes a decision, it evaluates several options and picks one. The rest disappear forever—you never see what it almost did or why it rejected the alternatives.

GhostTrace captures “Phantom Branches”: the actions your agent considered but rejected, along with the full reasoning for each rejection. All data is saved to a .ghost.json file that you can replay and inspect anytime.

Recording Example

ghosttrace record

✓ Recorded 4 decisions with 5 phantom branches
📄 Saved to gt_a1b2c3d4.ghost.json

Replay Example

ghosttrace replay gt_ghost.json --show-phantoms

Step 1: ✓ read_file → src/auth.py
👻 REJECTED: write_file (premature)
👻 REJECTED: search_codebase (too broad)

Installation

pip install ghosttrace

Links

• GitHub: https://github.com/AhmedAllam0/ghosttrace
• PyPI: https://pypi.org/project/ghosttrace/

Integration Options

GhostTrace is currently framework‑agnostic. Potential first integrations include:

• LangChain
• CrewAI
• OpenAI Agents SDK

Feedback

Feedback is very welcome—let me know what you think, if you’ll try it, or what features you’d love to see! 🔥