Concepts
Task threads
Git asks: what changed? Heddle asks: what was the task? The unit of work in Heddle is the task thread — a named, attributed, recoverable record that collects every capture, retry, abort, and conflict on the way to a signed merge. This page is the pillar concept the rest of the manual builds on.
Why threads, not commits
Git's history is a cleaned-up story. You write code, you stash, you try again, you squash, you write a polite commit message, you open a PR. The reviewer sees the polite version. The messy middle — every false start, every reverted experiment, every moment you almost shipped the wrong thing — never reaches the record.
That worked when the people doing the work were humans. Humans produce a tractable amount of messy middle. They self-curate. They throw most of the noise away before it ever becomes a commit.
Agents don't. An agent producing a refactor will run through dozens of captures, half a dozen retries, a few aborted paths, and one or two conflicts before reaching a merge. Git can't hold that shape — it has no native notion of a retry, an abort, an attribution, or a content-addressed state. Heddle does.
Anatomy of a thread
A thread carries five fields plus an ordered event list:
- A name.
task/biscuit-authzin our running example. Short, descriptive, namespaced bytask/. - An agent identity.
clauderunningopus 4.7fromanthropic. Read from the shell environment at capture time — no flags needed. - A delegator.
anan@heddle.sh— the human who handed the task to the agent. Carries authority for the thread. - A state.
hd-d01a8b4e— the content-addressed hash of the resolved working tree after the merge. Two threads with identical resolved content share a state ID. - A signature.
ed25519:a8f3c1d7— Ed25519 over the resolved state. Optional but cheap. The dedicated concept page on attribution and signing lands in the next docs pass; for today, seeheddle review sign.
Then the event list — every capture, retry, abort, and
conflict, in order. Run heddle thread show on the
running example and the shape is plain:
The resolved task as one record
bash$ heddle thread show task/biscuit-authztask/biscuit-authz · claude · opus 4.7 9 captures · 3 retries · 1 abort · 1 conflict · 1 test · 1 merge state hd-d01a8b4e · signed ed25519:a8f3c1d7 ✓ 2m 10s wall-clockCompared to Git
Most concepts in Heddle have a Git analogue. They aren't drop-in replacements — they're structurally different — but the analogy helps a Git-fluent reader find the right mental shelf.
git commit heddle capture Heddle captures aren't human-curated milestones. They're cheap, frequent snapshots — the messy middle as data. The thread collapses them at merge time.
git branch heddle thread A branch is a moving pointer. A thread is a named record with a defined endpoint. Branches forget; threads remember.
git stash heddle fork Stash drops on a typo. Forks persist, stay attributed, and stay browseable from heddle thread show <task>.<fork>.
git log heddle thread show Log is a stream of commits. Thread show is a single resolved record with its event tape — the same data, but structured.
git merge / git rebase heddle bridge git export Heddle does its own resolution internally. Bridging to Git produces a single signed commit on the bridged branch.
What changes when the unit is the task
Three things change about your week:
- You capture more. Captures are cheap and disposable by default. There's no reason to wait for a clean state — the thread will collapse the noise at merge time.
- You stop losing work. The abandoned forks stay. The retry that almost worked is still browseable. The conflict that interrupted you yesterday is still recoverable from the same thread you came back to today.
- Review changes shape. A reviewer who wants to see the diff sees the diff (same as Git). A reviewer who wants to understand how the agent got there can read the thread. Both audiences get what they need from the same record.
The commands that operate on threads
Three commands cover most of the day:
heddle init— set up the repo so threads can exist.heddle capture— snapshot the working tree into the current thread.heddle thread— the parent ofthread show,thread list,thread switch, and the rest of the thread-management family.
Read the CLI reference for the full list — every command, every flag, every example.