Time-Travel Chat: Forking Conversation Trees from a Checkpoint

Mechanically this is rehydration / resurrection — the conversational form of the snapshot-and-restore pattern from the computer-use work, where an agent's world is serialized and brought back to life to resume. Here the transcript prefix is the serialized state, the resumption point is a :uuid, and "forking forward" rehydrates that state into a live session that then goes somewhere new. The same shape recurs across the site: resurrecting Unix V4 from a saved disk image, and the reversible pipeline's "load a URL, the state hydrates." The novelty is only the medium — the state being rehydrated is a context window, and there can be many live resurrections of the same past, diverging.

The obvious move — filter to messages, then build the tree — is wrong. It shatters the graph:

(def msgs (filterv #(#{"user" "assistant"} (:type %)) es))
(chat/tree-shape msgs)
;; => {:nodes 3652, :roots 1, :leaves 608, :branch-points 11, :sidechains 0}

608 leaves with only 11 branch-points is impossible for a connected tree. The reason:

(let [muids (set (keep :uuid msgs)) alluids (set (keep :uuid es))]
  {:msg-parent->msg     (count (filter #(muids (:parentUuid %)) msgs))
   :msg-parent->sidecar (count (filter #(and (:parentUuid %)
                                             (not (muids (:parentUuid %)))
                                             (alluids (:parentUuid %))) msgs))
   :msg-parent->missing (count (filter #(and (:parentUuid %)
                                             (not (alluids (:parentUuid %)))) msgs))
   :msg-parent->nil     (count (filter #(nil? (:parentUuid %)) msgs))})
;; => {:msg-parent->msg 3055, :msg-parent->sidecar 596, :msg-parent->missing 0, :msg-parent->nil 1}

596 messages have a parent that is a sidecar, not a message. The parent chain weaves through non-message entries. So: build the DAG over the full uuid set; the message sequence is a projection of a root→leaf path. No edge ever dangles (missing is 0), which is itself a contract invariant worth asserting.

The API rejects an assistant tool_use block without a matching user tool_result, and vice versa. In a complete session the books balance to zero:

(let [blocks  (fn [t k] (set (for [e msgs c (get-in e [:message :content])
                                   :when (and (map? c) (= t (:type c)))] (k c))))
      uses    (blocks "tool_use" :id)
      results (blocks "tool_result" :tool_use_id)]
  {:tool_use (count uses) :tool_result (count results)
   :orphan-uses    (count (clojure.set/difference uses results))
   :orphan-results (count (clojure.set/difference results uses))})
;; => {:tool_use 962, :tool_result 962, :orphan-uses 0, :orphan-results 0}

This is the constraint that makes granular mutation hard. You cannot delete the assistant turn that emitted a tool_use without also deleting the user turn that carried its tool_result. The atomic unit of mutation is the tool-use/result pair — and, more conservatively, the turn — not the individual block. Compaction sidesteps this by always cutting at a turn boundary and replacing the prefix wholesale. Granular mutation has to honor the pairing explicitly.

Sidechain (sub-agent) results link back to the assistant that spawned them:

(frequencies (map #(boolean (:sourceToolAssistantUUID %)) es))
;; => {false 5515, true 962}   ; exactly the 962 tool results

So a tool result is reachable two ways — by parentUuid and by sourceToolAssistantUUID. Both must stay consistent under mutation, which is the concrete form of "sub-agents make it hard to track."

Specs describe a well-formed transcript and a valid projected path. They are the precondition and postcondition of any mutation.

(require '[clojure.spec.alpha :as s])

(s/def ::uuid       (s/nilable string?))
(s/def ::parentUuid (s/nilable string?))
(s/def ::type       #{"user" "assistant" "system" "summary"
                      "attachment" "mode" "queue-operation"
                      "permission-mode" "last-prompt" "ai-title"
                      "file-history-snapshot"})
(s/def ::entry      (s/keys :req-un [::type] :opt-un [::uuid ::parentUuid]))

;; corpus invariants --- hold before AND after a mutation
(s/def ::no-dangling-parents
  (fn [es] (let [ids (set (keep :uuid es))]
             (every? #(or (nil? (:parentUuid %)) (ids (:parentUuid %))) es))))

(s/def ::unique-uuids
  (fn [es] (apply distinct? (keep :uuid es))))

;; a projected root→leaf path is API-valid
(s/def ::tools-balanced
  (fn [path] (= (count (tool-use-ids path))
                (count (tool-result-ids path)))))
(s/def ::roles-alternate
  (fn [path] (->> path (map :type) dedupe (partition 2 1)
                  (every? (fn [[a b]] (not= a b))))))

Specs say what is valid; PBT says the operations keep it valid. Generate a random tree, apply an operation, assert the invariants. (Run under JVM Clojure via deps.edn's org.clojure/test.check; bb stays the exploration REPL.)

(require '[clojure.test.check.clojure-test :refer [defspec]]
         '[clojure.test.check.properties :as prop])

;; forking off any uuid leaves the parent's ancestry untouched
(defspec fork-preserves-ancestry 200
  (prop/for-all [t gen-transcript, u gen-existing-uuid]
    (let [t' (fork t u)]
      (= (ancestry t u) (ancestry t' u)))))

;; granular drop + reparent: no dangling edges, uuids stay unique,
;; and the projected path stays tool-balanced
(defspec drop-span-keeps-contract 200
  (prop/for-all [t gen-transcript, span gen-turn-span]    ; span = whole turns
    (let [t' (drop-span t span)]                          ; children reparented
      (and (s/valid? ::no-dangling-parents t')
           (s/valid? ::unique-uuids t')
           (s/valid? ::tools-balanced (project-current t'))))))

;; compaction is the degenerate case: drop-span where the span is a prefix
;; and the replacement is a single summary node. Same property, narrower input.
(defspec compaction-is-a-prefix-drop 100
  (prop/for-all [t gen-transcript, k gen-prefix-length]
    (s/valid? ::tools-balanced (project-current (compact t k)))))

The generators encode the domain: gen-turn-span only ever selects whole turns (so the tool pairing can be preserved), which is the property test discovering the atomic-unit rule for itself.

Every entry carries :version. Today it is uniform —

(frequencies (keep :version es))            ;; => {"2.1.161" 4447}
(->> (chat/list-sessions) (take 60)
     (mapcat #(keep :version (chat/read-session %))) frequencies)
;; => {"2.1.161" 5565}

— but the schema will drift across Claude Code releases (fields appear, summary entries change shape). So the reader should dispatch on :version against a registry of json-schemas, rather than assume one shape. The :version field is the dispatch key; a per-version schema validates each line and selects the right normalizer:

(def schema-registry
  {"2.1.x" "schemas/claude-jsonl-2.1.json"
   ;; "2.2.x" "schemas/claude-jsonl-2.2.json"  ; when it lands
   })

(defn normalize [entry]
  (let [v (:version entry)
        schema (lookup-schema schema-registry v)]
    (when-not (valid-against? schema entry)
      (throw (ex-info "unknown transcript shape" {:version v :entry entry})))
    (migrate-to-canonical entry v)))

This keeps the spec/PBT layer working on one canonical shape while json-schema absorbs the version churn at the boundary.

Append-only time-travel needs nothing destructive. If you instead want to edit history — a more granular compaction — you need two destructive primitives, and they carry the heavier contract (reparenting, tool-rebalancing) from the contract section above:

• drop-span(t, span) — remove whole turns; reparent survivors' children to the nearest surviving ancestor; the projected path must stay tool-balanced.
• compact(t, k) — the special case: drop a prefix, replace it with one summary node anchored by leafUuid. This is what the harness already does, coarsely.

These are strictly harder than time-travel, which is why time-travel is the place to start: it is pure addition over an immutable log.

aygp-dr's gemini-repl-007 roadmap sketched a "git for conversations" CLI — related, though its emphasis is fork-and-*rebuild*/compare rather than reuse-prefix-then-diverge:

gemini-repl fork  main-session --name "alternative-approach"
gemini-repl diff  session1 session2 --format markdown
gemini-repl merge session2 --into session1 --strategy insights-only
gemini-repl tree  my-session --format mermaid        # + auto_checkpoint: 5m

fork is exactly the time-travel primitive; tree is the read view from chat.clj. merge --strategy insights-only is the open research problem — a CRDT-shaped question (how do two divergent branches recombine without a human picking lines), and it only matters if branches ever rejoin. For pure time-travel they need not.

These fork markers are our experiments, not Claude Code's real history. Left in, they inflate every count — branch-points, leaves, forks. So the analysis layer excludes anything we minted; the marker is the discriminator (:type "fork" / :origin "wal-sh-repl"), and chat.clj filters it before any breakdown:

(defn test-fork? [e]
  (or (= "fork" (:type e)) (= "wal-sh-repl" (:origin e))))

(chat/breakdown)                          ; real harness history only (default)
(chat/breakdown chat/projects-root true)  ; include our experimental forks

Two record sets, kept apart: the history the harness wrote, and the speculative branches we graft on.

The fork is not hypothetical. chat.clj/fork-session writes a new session whose history is the file prefix up to a chosen :uuid, under a fresh id; the source is untouched (append-only). Forking the Lodestar session at its codename turn (8cc36543) produced a 6-node prefix; claude -r <new-id> resumed it — the harness loaded the forged branch as its own session, rehydrated the pre-fork context (it recalled the codename "Lodestar"), and continued a new direction (a second codename, "Sextant", for the branch). Reading both transcripts back:

original path : 19 nodes  root .. Lodestar
fork path     : 20 nodes  root .. Sextant
shared prefix :  6 nodes  ending at the fork point 8cc36543
                 (then 62a7353c on the original, 1d9b708d on the fork)

So you can implicitly fork Claude's history and step back to a prior point: forge a transcript that ends at the fork, give it a new id, claude -r it. The harness need not know it is a fork — it loads any valid <id>.jsonl. The two sessions share the prefix uuids (structural sharing on disk) and diverge after the fork point: a version DAG, built by the REPL. This is the v1 of the capability — read, fork, resurrect — with the REPL as the whole interface.

Branching is the model developers already avoid. Git branches are the canonical example: cheap, safe, structurally shared — and still the thing most engineers misuse, abandon stale, or merge in a panic. A conversation tree inherits every one of those failure modes and adds none of git's tooling. If git branch needed a decade of porcelain to become bearable, a hand-driven chat fork starts from zero.

The harness is a TUI, and a TUI renders a tree poorly. Linear scrollback is the medium. Put eleven fork points and fourteen live tips in a single session — the real numbers from one transcript — and you lose your place on the first jump back. Context-switching between siblings carries the full cost of rereading a divergent prefix, and sidechains multiply the branch count past what anyone holds in working memory. The guile-sage work taught the inverse lesson: the REPL is bearable precisely because it is one line of evaluated state, not a graph the operator must navigate.

The analogy that sells the idea also condemns it. Choose Your Own Adventure, branching screenplays, Bandersnatch — interactive fiction never went mainstream because branching narrative explodes on both ends: authoring cost and consumption cost compound with every node. Netflix stepped back. A branching chat is the same combinatorial trap with no author and a reader who is also the writer.

To make it hand-usable you would need ref management, a genuine tree view, context-window diffing between siblings, and resumption-point validation (only tool-balanced turn boundaries are legal fork points). That is a second product bolted onto the harness. The payoff is "what if turn 40 went the other way" — answered more cheaply by starting a new session. The harness exposes none of this, and that is the correct decision. The deliverable is the spec and the REPL. There is no tool here.

A full tree explorer never shipped, but a partial one is already in the harness. esc esc rewinds "up a few messages" — time-travel to an earlier checkpoint you then continue differently. Ctrl+O expands collapsed lines: the partial- persistence read view. And the boundary shows in the wild — /compact can fail with Conversation too long … press esc twice to go up a few messages and try again, which is the partial→full edge surfacing, its suggested fix literally "travel back and diverge." The implicit UI exists; what is missing is only the explicit tree — which, per the section above, is the part that does not pay for itself.

There is even a CLI surface for the primitives. claude -r <uuid> --fork-session resumes a named session and branches it ("fork instead of mutate") — the shipped form of fork(t, uuid); claude --session-id $(uuidgen) mints a chosen GUID (the fork-protocol's "new GUID" step); claude -c / claude -r <id> resume the current or a named conversation (partial persistence); and /compact plus the PreCompact hook are the coarse-mutation cousin. The primitives ship; only the tree view does not. Catalogued in the Claude Code workshop and the cross-CLI coding-agents review (whose non-Claude flag claims are point-in-time and need dated re-verification — see annotation systems).

Speculative — under team review. The sections above rest on REPL evidence; this is a conjecture about where confluence becomes tractable.

The smallest leaf that obeys both contracts at once — the conversation contract (a valid transcript) and the artifact contract (a Racket -> contract on the succ=/=add primitives). It checks that (0+1)+40+(0+1) = 42 no matter how you group it.