Show HN: Tooltrace – Record and replay LLM tool calls locally (zero dependencies, written in Go)

The Problem & The Solution

AI agent frameworks log tool calls inconsistently and rarely validate arguments beforehand, forcing developers to re-run expensive, non-deterministic LLM sessions to debug failures. tooltrace addresses this by isolating tool execution as a primitive (name, arguments) -> result, recording the lifecycle to a standard append-only .jsonl trace file to decouple debugging and testing from specific LLM providers.

• Repository:

  tijani-web / tooltrace

  tooltrace sits between your LLM agent and the tools it calls. It records every tool invocation to a portable trace file, and lets you replay, validate, diff, and inspect that trace later — without depending on any specific LLM provider, framework, or SDK.

  tooltrace

  

  Record and replay LLM tool calls.

  tooltrace sits between your LLM agent and the tools it calls. It records every tool invocation to a portable trace file, and lets you replay, validate, diff, and inspect that trace later — without depending on any specific LLM provider, framework, or SDK.

  ---

  ⚠️ Security / Privacy Notice

  Trace files record raw tool arguments and results verbatim. This means they may capture API keys, auth tokens, passwords, or PII that were passed to or returned by your tools.

  In v1 and v2, there is no automatic redaction. You are fully responsible for securing your trace files:

  • Add *.jsonl to your .gitignore.
  • Restrict file permissions in production.
  • Do not attach raw trace files to public GitHub issues or share them on Slack without manual scrubbing.

  Note: Automatic, field-level redaction is on the roadmap for v3.

  ---

  Why this exists

  Every agent framework logs…

  
  

  View on GitHub

  
  
• Tech Stack: 100% Go standard library (zero external dependencies).

How It Works

1. Record the Trace (Go Library)
   
   Wrap your agent's tool execution in trace.Record to manage timing, capture statuses, and append execution data to your session file. For full code implementation details, please refer to the repository.

2. Replay and Verify (CLI)
   
   Replay recorded traces locally using a mocks.json file to verify downstream tools without re-invoking the LLM via the CLI replay engine.

Core Philosophy & Design Choices

• Concurrency-Safe: Handles concurrent, multi-threaded tool streams natively.
• Grep-able Contracts: Flat, portable .jsonl schema suited for CLI text processors.
• Framework Agnostic: Works independently of tools like LangChain or LlamaIndex.

What's Next?

Currently at v1 (Record + Replay), the roadmap includes automatic PII/auth token redaction for v3, JSON Schema validation, and automated diffing states.

---

What edge cases or challenges did you run into while implementing the concurrency-safe design in the Go standard library? I'd love to hear your thoughts in the comments below!

Comments

[Basit Tijani]

Hey everyone, author here! I built tooltrace because I got tired of wasting money re-running expensive LLM agent sessions just to debug an API tool failure locally.By treating the tool call as a simple (name, args) -> result primitive, we can replay and diff traces instantly without any complex framework setup.It's completely dependency-free and built on Go's standard library. I'd love to hear your thoughts on the schema, or how you currently handle agent observability in production!