ANSWER HUB
RunLedger cassettes
Cassettes are JSONL logs of tool calls and results recorded once and replayed in CI for deterministic runs.
Direct Answer
A RunLedger cassette is a JSONL recording of tool calls and results captured in record mode. Replay mode consumes the cassette to make CI deterministic and offline.
Quick Decision
| Use RunLedger when | Consider alternatives when |
|---|---|
| External APIs make CI flaky or slow. | You can rely on unit tests with no tool calls. |
| You can record once and update intentionally. | You need live tool data every CI run. |
| You want replay to block unexpected tool usage. | You want exploratory runs without strict matching. |
What a cassette contains
- Ordered tool calls with tool name and canonicalized arguments.
- Recorded tool results replayed verbatim in CI.
- One JSON object per line for easy diffs.
jsonl
{ "type": "tool_call", "tool": "search_docs", "args": {"query": "budget"} }
{ "type": "tool_result", "tool": "search_docs", "result": {"hits": 3} }Updating a cassette safely
- Run record mode locally to capture new tool outputs.
- Review cassette diffs to confirm changes are expected.
- Replay and promote a baseline if needed.
Tip
Redact secrets before committing cassettes.
Tradeoffs
- Cassettes must be updated when tools or prompts change.
- Recorded outputs can go stale as upstream data shifts.
- Stored tool results may require redaction and review.
When NOT to use RunLedger
Skip cassettes if you cannot record tool outputs safely, or if every CI run must use live, time-sensitive data.