Compare

git worktree

Worktrees isolate files. They do not version the failed approach.

A worktree is a second checkout of the same repository. Claude Code's own docs tell you to use one per session so two agents do not share a working tree. That is correct, and it is enough when the only problem you have is collision.

What a worktree does not keep: the retry, the abort, the discarded shim, the reason the first session walked away. When you remove the directory, the failed approach is gone. Isolation is a filesystem property. A record is not.

Use a worktree when you need two working trees and you will remember what happened.

Use Heddle when the failed approach has to remain a named, attributable thread a person can review after the directory is gone.

heddle start still uses an isolated checkout. The difference is the thread that checkout is bound to.

jj (Jujutsu)

jj is a better Git. Heddle is a different unit of work, then a different store.

jj keeps the Git object graph (or interops with one), drops the index, treats the working copy as a commit, and makes conflicts first-class. If your pain is git rebase, the index, or “I want the Git model without the Git UX,” jj is the honest answer. The unit is still the commit. The store is still Git.

Heddle's unit is the thread: captures, retries, aborts, attribution, then land. Overlay mode keeps Git as the source of authority. Adopt mode makes Heddle the store and Git the export. Those are different bets from “a nicer frontend on the same graph.”

Use jj when you want a better interface to Git's unit of work.

Use Heddle when the unit of work is the agent task, and you need the messy middle as data, not as a commit you will squash.

You can run Heddle as an overlay on a repo you also use with jj. That is an overlay question, not a conversion.

GitButler

GitButler makes Git nicer. We overlay, then replace the source of authority when you are ready.

Virtual branches, hunk staging, a GUI that can hold parallel work in one working tree. GitButler is a better way to operate Git. It does not change what Git records. Agent attribution is still a commit message you hope someone wrote. The failed approach is still whatever did not get staged.

Use GitButler when Git is the system of record and you want the day to hurt less.

Use Heddle when you want the agent record now (heddle init) and, later, Heddle as the source of authority (heddle adopt). Git stays the export.

Entire

Entire stores the transcript after. We inject before the next edit.

Entire hooks your Git workflow, checkpoints agent sessions, and writes transcripts, prompts, tool calls, and attribution onto shadow refs or refs/entire/checkpoints/, linked to the commit that resulted. That is archaeology: why this commit exists, recoverable after the fact. Useful. Git remains the store.

A Heddle annotation is attached to a file or a symbol (heddle context set --path … --scope symbol:authorize --kind invariant) and is what the next agent sees when it opens that symbol. The reasoning is in the way of the next edit, not in a checkpoint you search later.

Use Entire when you want the session transcript bound to the Git commit you already made.

Use Heddle when the next agent has to inherit the decision before it touches the function.

These can coexist. Entire is a Git-side record of a session. Heddle annotations are a repo-side record on the code.

Oak

Oak replaced Git as a religion. We overlay first, adopt when ready, export is Git.

Oak is a new VCS: branch-per-session, lazy mounts, content-addressed storage, Git export as an interoperability hatch. The bet is that agents need a different substrate, so you start there. Fine if you want that conversion on day one.

Heddle's bet is the other order. heddle init in the repo you already have. People who have not installed Heddle keep using Git. heddle adopt is the day Heddle becomes the source of authority. heddle export git / heddle commit write a byte-identical Git graph. You can leave without a conversion story.

Use Oak when you want a new VCS and you will export to Git when someone asks.

Use Heddle when you will not win a “replace Git” argument this quarter, and you still need a record of agent work.

The three verbs

You do not have to adopt. A lot of teams will live on overlay and export forever. That is a supported shape, not a halfway state.

Related

• Git overlay
• Task threads
• Adopting an existing repo
• Annotating for the next agent
• Bridging back to Git