HEDDLE

Guide

Forking and recovering

You're mid-refactor. Two approaches look defensible; you don't know which will win until you try. Heddle's answer is fork — branch the working state forward into a second thread, let both paths run, recover whichever one wins. This guide walks the workflow end-to-end.

When to reach for fork

Fork is for genuine uncertainty — two approaches both defensible, no way to know which pays off without trying. Don't fork for every disagreement; threads can hold retries and aborts inline. Reach for fork when:

  • A second agent will explore in parallel.
  • You want to keep the not-yet-resolved path as evidence of what was considered.
  • The decision is reversible and the cost of being wrong is a few hours of agent time.

Read the fork-from-capture concept page first if you want the full mental model. This guide is the operational walk-through.

1. Create the fork

From any state, run heddle fork. Two flags matter:

  • --from <state> — the fork point. Accepts a state ID, a marker, HEAD, @, or HEAD~N. Defaults to HEAD.
  • --name <thread> — attach the fork to a named thread. Without this, the fork is detached but still addressable by state ID.

Fork the current state into a named thread

bash# team is unsure whether to keep a JWT compat layer$ heddle fork --name task/biscuit-authz.shimCreated fork hd-9c41 on thread 'task/biscuit-authz.shim' from hd-d01a8b4e

The parent thread keeps running. The fork is now its own thread with its own working state, its own captures, its own agent identity if you set one. Switch back and forth with heddle thread switch.

2. Let the fork run

From here, the fork behaves like any other thread. Make changes, capture, retry, sign. The parent and the fork have no special relationship beyond the shared ancestor at the fork point.

Work on the fork

bash$ heddle thread switch task/biscuit-authz.shim# try the JWT compat layer approach$ heddle capture --intent "keep JWT compat layer"Captured state hd-9c4a (7e2c8b91)$ heddle capture --intent "two auth lanes drift; 4 tests fail"Captured state hd-9c5e (ab02174d)

3. Abandon if it doesn't pay off

Heddle distinguishes dropping a thread (no further work; mark abandoned but keep the record) from destroying it (which Heddle never does). To stop work on the fork:

Drop the fork as abandoned

bash$ heddle thread drop task/biscuit-authz.shimDropped task/biscuit-authz.shim · marked abandoned

The thread is now flagged abandoned — it won't appear by default in heddle thread list — but everything in it persists. The captures stay attributed and addressable. The agent identity and the reason for abandoning are part of the record.

4. Inspect an abandoned fork later

Months later you might want to revisit what was abandoned. heddle thread show renders it as a single record:

Read an abandoned fork's record

bash$ heddle thread show task/biscuit-authz.shimtask/biscuit-authz.shim   ·  gpt · 5.4 · forked from hd-d01a8b4e  3 captures · 4 retries · 1 abort (cost outweighs migration)  state: abandoned · still addressable

Add --include-auto to heddle thread list if you want abandoned threads to surface in the default list view.

5. Recover from any state

If the abandoned path becomes interesting again — different constraints, new context, a teammate's question — heddle goto <state> lands you back at any capture in any thread.

Resume from an abandoned fork's mid-state

bash$ heddle goto hd-9c4aSwitched to state hd-9c4a on thread task/biscuit-authz.shim

From there you can fork again, continue the abandoned thread, or just inspect the working tree to remember what was there.

Next

  • Fork from capture — the conceptual depth: why this isn't just git stash with extra steps.
  • heddle fork — the full flag surface.
  • heddle thread — the thread management family (switch, list, drop, cleanup, and 13 more).