Session Trees vs. Git Worktrees: Understanding Two Layers of Agent Branching

The Multi-Agent Branching Problem

When you start building AI agents that write code, you quickly run into a problem: how do you let agents work on multiple things at once without stepping on each other? The answer involves two very different kinds of branching. One operates on files. The other operates on the agent's reasoning. Understanding both is essential if you want to build reliable multi-agent coding systems.

Git Worktrees: Isolating the Filesystem

Git worktrees are a built-in Git feature. They let you check out multiple branches of the same repository at the same time, each in its own directory. Instead of switching branches and losing your place, you just create a new working directory pointing to a different branch.

For coding agents, this is incredibly useful. When you spawn a sub-agent to work on a task, you create a worktree on a feature branch like task/fix-login-bug. The agent works inside that directory, makes changes, and commits. Meanwhile, another agent can be working in a different worktree on task/add-search. Neither agent touches the other's files.

This is the approach used in production systems today. A main orchestrator agent receives a task, clones the repo (or uses an existing clone), creates a git worktree for the sub-agent, mounts that worktree into a sandboxed container, and lets the agent work. When the agent finishes, the host pushes the branch and opens a pull request. The worktree gets cleaned up. Clean, simple, battle-tested.

Git worktrees solve a real problem. But they only solve one layer of it.

Session Trees: Isolating the Reasoning

Here is the gap that worktrees do not cover. An AI agent is not just a process that edits files. It is a reasoning system. It reads a prompt, makes decisions, calls tools, observes results, and adjusts its approach. That chain of decisions is the agent's context. And when something goes wrong at step 47 of a 60-step task, you have a problem.

With only git worktrees, your options are limited. You can look at the git diff to see what changed, but you have no record of why. You cannot rewind the agent's thinking to the exact point where it made a bad call and try again from there. You would have to restart the whole session from scratch.

This is the problem session trees solve. A session tree stores the agent's entire conversation history as a tree structure. Each message has an ID and a parent ID. The conversation is not a flat list. It is a tree, and you can branch from any node.

If the agent produced a bad result, you find the message where it went off track, fork from the previous message, and let it try again. The new branch has all the original context up to that point. The agent does not lose its understanding of the task, the codebase, or the decisions it made earlier. It just gets a second chance from the exact right moment.

Why You Need Both

These two systems are complementary, not competing. They operate on completely different things.

Git worktrees isolate code. Session trees isolate reasoning.

A sub-agent spawned with both gets its own filesystem (so it cannot corrupt another agent's in-progress work) and its own conversation branch (so its reasoning chain stays clean and traceable).

Consider a practical scenario. You have a main orchestrator agent managing five tasks. It spawns five sub-agents in parallel. Each sub-agent gets:

• A git worktree on its own feature branch, so file changes stay isolated.
• A session tree branch, so its reasoning context is independent.

Sub-agent three fails because it chose the wrong approach. With just git worktrees, you would reset the branch and re-run the entire agent session. With session trees, you branch from the point just before the bad decision and let it try a different approach. It keeps all the context it built up during the first 30 steps. Only the bad decision gets replaced.

What Session Trees Actually Store

The implementation is straightforward. Sessions are stored as JSONL files. Each entry is a JSON object with fields like id, parentId, role, content, and toolCalls. Because every entry points to its parent, the structure is naturally a tree.

Branching means adding a new entry with the same parentId as the entry you want to branch from. No new files are created. No data is duplicated. The branch exists in-place in the same JSONL file.

This is much lighter than git branching. There is no filesystem overhead. No checkout. No merge conflicts. It is purely a data structure for organizing an agent's conversation history.

When to Use What

If you only need filesystem isolation (one agent, one task, no retries), git worktrees alone are fine. They are simple, well-understood, and every developer already knows how they work.

If you need to manage an agent's reasoning history (retrying from specific points, exploring alternative approaches, tracing why an agent made a particular decision), you need session trees.

If you are building a production multi-agent system where sub-agents work in parallel and you want both code isolation and reasoning traceability, you use both together.

The Practical Reality

Most real-world agent orchestration systems use git worktrees for the mechanical part: keeping file changes separate. Session trees add the cognitive layer on top: tracking, branching, and replaying agent reasoning.

Think of git worktrees as giving each agent its own desk. Session trees give each agent its own notebook. The desk keeps their papers from mixing together. The notebook lets you flip back to page 12 and start a new draft from there without losing everything that came before.

Neither replaces the other. A robust agent system uses both layers, one for code and one for context, to keep multi-agent workflows clean, traceable, and recoverable.

Conclusion

Building reliable multi-agent coding systems requires thinking about isolation at multiple levels. Git worktrees solve the file-level problem elegantly, but they don't address the reasoning layer. Session trees fill that gap by making conversation history branchable and replayable.

For simple use cases, git worktrees alone might be sufficient. But as soon as you need agents to work in parallel, retry from specific failure points, or trace how decisions were made, you need both systems working together. The combination gives you complete isolation: agents cannot corrupt each other's code, and you can always rewind and explore alternative reasoning paths.

This is the architecture that scales. This is how you build multi-agent systems that are both powerful and debuggable.