Documentation

tracellm replay

Replay a recorded execution timeline.

Overview

The tracellm replay command fetches a saved trace from SQLite and re-executes its timeline step by step in the terminal. Each step is rendered with a tree visualization showing the execution order, status, input, and output.

Tracey Tip

Replay helps you understand agent decisions. Instead of reading logs backwards, you watch the execution tree step by step — seeing exactly which tool was called, what it returned, and how the agent decided to proceed.

Syntax

terminalCopy

bash

tracellm replay [OPTIONS] TRACE_ID

Argument	Type	Required	Description
TRACE_ID	string	Yes	The trace ID to replay (e.g. tr_2kf9q3m1)

Option	Type	Default	Description
--speed	float	1.0	Replay speed multiplier (min 0.1)
--show-response	flag	false	Print the full saved response after replay

What Happens Internally

Fetches the trace from SQLite by ID via fetch_trace.
Renders metadata — trace ID, status, latency, retry count, and step count in a replay header panel.
Iterates steps using Rich Live display. For each step it renders an execution tree showing which steps are completed (✓), active (▶), and pending, alongside a detail panel with tool name, duration, status, input (clipped to 200 chars), and output (clipped to 200 chars).
Throttles timing — waits duration / 1000 / speed seconds between steps, clamped between 80ms and 550ms.
Prints final report — a summary table plus a response preview (up to 600 chars). If --show-response is set, the full response is printed.

Example Output

Terminal outputCopy

text

  Replaying execution timeline...

  ╭── Replay ────────────────────────────────────────────────╮
  │                                                          │
  │  trace_id   tr_2kf9q3m1                                  │
  │  status     SUCCESS                                      │
  │  latency    3420.00 ms                                   │
  │  retries    1                                            │
  │  steps      9                                            │
  │                                                          │
  ╰──────────────────────────────────────────────────────────╯

  ╭── Replaying step 3/9 ────────────────────────────────────╮
  │                                                          │
  │  ╭── Execution Timeline ─────────────────────────────╮   │
  │  │                                                    │   │
  │  │  ✓ query.embed                                     │   │
  │  │  ✓ vector.search                                   │   │
  │  │  ▶ context.rerank                                  │   │
  │  │  ○ agent.plan                                      │   │
  │  │  ○ context.allocate                                │   │
  │  │  ○ tool.chain                                      │   │
  │  │  ○ llm.generate                                    │   │
  │  │                                                    │   │
  │  ╰────────────────────────────────────────────────────╯   │
  │                                                          │
  │  ╭── Step Detail ────────────────────────────────────╮   │
  │  │                                                    │   │
  │  │  step       3/9                                    │   │
  │  │  tool       context.rerank                         │   │
  │  │  duration   340 ms                                 │   │
  │  │  status     OK                                     │   │
  │  │  input      {"query": "Explain transformers",...}  │   │
  │  │  output     {"reranked": true, "matches": 5}       │   │
  │  │                                                    │   │
  │  ╰────────────────────────────────────────────────────╯   │
  │                                                          │
  ╰──────────────────────────────────────────────────────────╯

  Replay complete

Common Errors

Error	Cause	Fix
Trace not found	Invalid trace ID or trace was deleted	Verify the trace ID with tracellm export or the dashboard
No steps to replay	Trace exists but has no recorded steps	Some traces may be empty — check the trace in the dashboard
SQLite connection failed	Database file is missing or corrupted	Ensure ~/.tracellm/traces.db exists — it is created automatically on first run

Troubleshooting

Tip

Use --speed 2 to replay twice as fast for quick debugging, or --speed 0.5 to watch each step in slow motion.