Quickstart

Before you start

You need heddle on your $PATH. If heddle --version doesn't return cleanly, go back to the Install page.

Use any Git repo with at least one commit. The example here uses a fresh checkout of a real project. Change directory into yours and follow along.

1. Initialise Heddle

Inside the repo, run heddle init. Heddle writes a .heddle/ sidecar next to .git/ and runs in Git-overlay mode: Git commits stay in .git, Heddle metadata lives in .heddle. Your Git-tracked files are left untouched.

Initialise beside an existing Git repo

bash$ cd my-repo$ heddle initInitialized Heddle data in /path/to/my-repo/.heddle for Git-overlay workflowsSide effects:  - created Heddle sidecar for the existing Git repository  - left Git-tracked files untouched

If you want to see what Heddle thinks of your repo, run heddle status. It reports the current thread, the bridged Git ref, and whether the working tree has uncommitted changes.

2. Start a task

Heddle's unit of work is the task. Start one with a name that describes the goal, same shape as a good branch name, but in Heddle a task isn't a branch, it's a thread that will collect every capture, retry, abort, and conflict on the way to a merge.

Name the task

bash$ heddle start biscuit-authz --task "replace JWT auth with Biscuit capabilities"Started isolated thread 'biscuit-authz'

Thread names use letters, digits, and _ - . / @ : + =, no spaces. The human-readable goal goes in --task.

3. Capture as you work

Make changes the way you normally would. When something is worth recording, a passing test, a working prototype, the moment before a refactor, capture it. Captures are cheap. Capture often.

Snapshot the working tree into the thread

bash$ heddle capture -m "scaffold biscuit verifier"Captured state hd-rppffbae2jb2 (7efea517)$ heddle capture -m "wire datalog scope rules"Captured state hd-mts0jaw6666j (d82419fd)$ heddle capture -m "fix type error in handler"Captured state hd-q4k7zv1n8w0c (3b1f0a92)$ heddle capture -m "fix import path"Captured state hd-8e2hytr5pqxf (a5c4d017)

Every capture is part of the same thread, false starts and fixes alike. Heddle keeps each one in the thread's record, so the messy middle stays recoverable while the merge surface reflects the path that actually worked.

4. Read the resolved thread

Anytime, ask Heddle to render the task as a single record. heddle thread show collapses the captures, retries, and any conflicts into one reviewable surface.

Read the task as one record

bash$ heddle thread show biscuit-authzbiscuit-authz   ·  anthropic/claude-opus-4-8  9 captures · 3 retries · 1 abort · 1 conflict · 1 test · pending merge  state hd-rppffbae2jb2 · 2m 10s wall-clock  14:32:01 CAP  scaffold biscuit verifier  14:32:08 CAP  add Capability + Scope types  14:32:14 RET  type error in handler  ...  14:34:11 MRG  sign merge · ed25519

5. Mark it ready

When the task is done, ask Heddle for its verdict. heddle ready captures any outstanding work, checks conflicts, blockers, freshness, and semantic risk, then marks the thread ready or blocked and prints the next action. It never lands or pushes; it's the go/no-go check before you integrate.

Get Heddle's integration verdict

bash$ heddle ready --thread biscuit-authzThread 'biscuit-authz' is ready to landNext: heddle land

6. Land back to Git

Finally, hand the resolved task back to Git. heddle land captures any outstanding work, refreshes against the target when safe, lands the thread, and writes the Git checkpoint, squashing the thread into a single commit by default. Pass --push to push in the same step. It fails closed if conflicts or other blockers remain.

Integrate the thread and write the Git checkpoint

bash$ heddle land --thread biscuit-authzLanded 'biscuit-authz' · Git checkpoint f02d14ea

That's the whole loop. Push the Git commit, open a PR the way you always have. Reviewers who want to see the messy middle can open the linked Heddle thread; reviewers who only care about the diff see only the diff.

Next

Now read about task threads, the pillar concept that makes the rest of Heddle make sense. Or skip to the CLI reference and look up a specific command.