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/ directory next to .git/, reads the current branch, and adopts it as the main thread. Nothing in Git is touched.

Adopt an existing Git repo

bash$ cd my-repo$ heddle initinitialized · git-overlay mode · adopted main

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 "replace JWT auth with Biscuit capabilities"created task/biscuit-authz · state hd-d01a8b4e

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-9a1c$ heddle capture -m "wire datalog scope rules"Captured state hd-9a2f$ heddle capture --retry -m "type error in handler"Captured state hd-9a3e · marked retry$ heddle capture -m "fix import path"Captured state hd-9a44

Notice the third capture is flagged --retry. Heddle treats it as part of the same task — the thread keeps the retry in its record, but the resolved state at the end will reflect 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 task/biscuit-authztask/biscuit-authz   ·  claude · opus 4.7  9 captures · 3 retries · 1 abort · 1 conflict · 1 test · pending merge  state hd-d01a8b4e · 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. Sign the merge

When the task is ready for human review, sign it. The signature is over the resolved state — not the individual captures. Other reviewers can co-sign without rebuilding the artefact.

Sign the resolved state

bash$ heddle review sign task/biscuit-authzSigned task/biscuit-authz · ed25519:a8f3c1d7

6. Bridge to Git

Finally, hand the resolved task back to Git as a single, signed commit. Your normal PR workflow is unchanged — the commit message is the task name, the body summarises the captures, and the signature is preserved in the commit trailer.

Export as a Git commit

bash$ heddle bridge git export task/biscuit-authzExported to git: commit f02d14ea  message: 'task/biscuit-authz · replace JWT auth with Biscuit capabilities'  trailer: Signed-off-by: claude · ed25519:a8f3c1d7

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.