DEV Community

Ahmed Allam
Ahmed Allam

Posted on

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

#agents #ai #cli #showdev

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.

I built GhostTrace to fix that.

It captures "Phantom Branches": the actions your agent considered but rejected, with the full reasoning for each rejection. Everything is saved to a .ghost.json file that you can replay and inspect anytime.

Quick Demo 

ghosttrace record
Enter fullscreen mode Exit fullscreen mode 
✓ Recorded 4 decisions with 5 phantom branches
📄 Saved to gt_a1b2c3d4.ghost.json
Enter fullscreen mode Exit fullscreen mode 
ghosttrace replay gt_ghost.json --show-phantoms
Enter fullscreen mode Exit fullscreen mode 
Step 1: ✓ read_file → src/auth.py
👻 REJECTED: write_file (premature)
👻 REJECTED: search_codebase (too broad)
Enter fullscreen mode Exit fullscreen mode

Super simple to get started:

pip install ghosttrace
Enter fullscreen mode Exit fullscreen mode

It's framework-agnostic for now, but what should I integrate first?

LangChain? CrewAI? OpenAI Agents SDK?

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

ai #agents #python #opensource #machinelearning #debugging #llm 





![ ](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/nvd4317vowb62srn3hqx.png)
Enter fullscreen mode Exit fullscreen mode

Top comments (0)