Skip to content

Time-Travel Debugging

VlinderCLI records every agent interaction as a node in a content-addressed DAG. This enables you to inspect history, rewind to any completed turn, fork a new timeline, and continue from there.

View Session History

List sessions for an agent:

vlinder session list my-agent

Inspect a specific session's turns and messages:

vlinder session get ses-abc12345

Inspect a Turn

To see every message in a single turn (invoke, requests, responses, complete):

vlinder turn get sub-001

This shows all DAG nodes belonging to the submission in order — useful for understanding exactly what happened during a turn.

Fork from a Known-Good Point

Identify the DAG node hash you want to rewind to using vlinder session get, then fork:

vlinder session fork ses-abc12345 --from a1b2c3d4 --name fix-typo

This creates a new timeline branch called fix-typo, restoring agent state to that point.

Continue on the Forked Timeline

Run the agent on the forked branch:

vlinder agent run my-agent --branch fix-typo

You're now in the REPL at the historical state. Continue the conversation, taking a different path.

Promote the Fixed Timeline

After verifying the forked branch works correctly, promote it:

vlinder session promote fix-typo

This seals the old timeline (relabeled as broken-YYYY-MM-DD) and makes the forked branch the active one. Nothing is deleted — the old timeline is preserved.

Workflow Example

# 1. Run your agent
vlinder agent run todoapp

# 2. Something goes wrong — inspect the session
vlinder session list todoapp
vlinder session get wired-pig-543e

# 3. Find the last good turn and fork
vlinder session fork wired-pig-543e --from a1b2c3d4 --name fix-2026-03-11

# 4. Run the agent on the forked branch
vlinder agent run todoapp --branch fix-2026-03-11

# 5. Promote the fixed timeline
vlinder session promote fix-2026-03-11

How It Works

  • Every message (invoke, request, response, complete) is recorded as a node in a content-addressed Merkle DAG stored in SQL
  • Each completed turn produces a state hash — the agent's exact state at that point
  • Forking creates a new timeline branch, restoring the agent's state from the DAG
  • The conversations git repo at ~/.vlinder/conversations/ provides a read-only projection for browsing with standard git tools

For the full design, see Time Travel and Timelines.

See Also