Debugging LLM agents has long been a nightmare of non-determinism and wasted tokens. Most devs tweak a prompt, re-run the entire chain, and hope the output changes in the right way. It is slow, expensive, and statistically insignificant. A new tool called Agentfork aims to fix this by allowing developers to fork an agent’s execution at any specific step, replay previous steps from cache, and sweep multiple variants of the failing step to determine the actual fix.

The Problem With 'One Lucky Run'

Agentfork, released by developer bimal1023, addresses the core inefficiency of agent development: the full re-run loop. When an agent fails at step 3, re-running steps 1 and 2 wastes tokens on code that didn’t change. Worse, a single successful re-run proves nothing. Agentfork records every LLM and tool call locally, allowing users to replay earlier steps from a cache. This means only the problematic step incurs new API costs. The tool runs multiple variants of that step in parallel, providing pass rates instead of anecdotes.

A Practical Example: The Cents Bug

The repository’s headline example illustrates the power of this approach. A refund agent misinterpreted an API response where the amount was in cents (4999) rather than dollars, resulting in a $4,999 refund for a $49.99 laptop. Using Agentfork’s sweep command, the developer tested two fixes: switching to a larger model (gpt-4o) and adding a specific system prompt instruction about dividing by 100. The larger model failed to fix the issue across three runs and cost 15x more per run. The prompt addition, however, achieved a 3/3 pass rate for a fraction of a cent. This evidence-based debugging replaces guesswork with data.

Integration and Local-First Philosophy

Agentfork is designed for privacy and speed. It runs entirely locally with no account required, ensuring no data leaves the machine. Integration is minimal: developers wrap their OpenAI or Anthropic client with wrap_openai or wrap_anthropic, decorate tool functions with @tool, and mark the main agent function with @trace. Each run is saved to a local SQLite database (.agentfork/traces.db). The tool supports LangGraph integration and provides a local web UI for browsing traces, forking steps, and comparing runs side-by-side.

Current Limitations and Roadmap

While powerful, Agentfork is not yet a complete solution for all agent architectures. The current version does not support streaming models or the OpenAI Responses API. However, the roadmap includes expanding provider support and refining the cost estimation logic. The tool overlaps with other record/replay utilities like agent-rewind and agentstep, but its focus on sweeping variants with pass rates distinguishes it as a debugging-first tool rather than just a trace viewer.

Key Takeaways

  • Agentfork enables deterministic replay of LLM agents from any step, caching prior executions to save costs.
  • The 'sweep' command tests multiple prompt or model variants in parallel, returning statistical pass rates.
  • A real-world example showed a simple prompt fix was more effective and cheaper than upgrading to a larger model.
  • The tool is MIT-licensed, runs locally, and supports OpenAI, Anthropic, and LangGraph.
  • Limitations exist: streaming models and the OpenAI Responses API are not yet supported.

The Bottom Line

Agentfork turns agent debugging from a black art into a measurable engineering discipline. If you’re tired of burning tokens on full re-runs, this tool is a necessary addition to your stack.