Adopting an existing repo

Before you start

You need a working heddle binary on $PATH. If heddle --version doesn't return cleanly, finish the install page first. You also need a Git repository with at least one commit.

Then ask Heddle where you are before changing anything. heddle status is observe-only: it creates no .heddle, exits 0 in a plain Git checkout, and prints the exact next command.

The safe probe — this writes nothing

bash$ cd my-repo$ heddle statusHeddle statusRepository: Git repo (setup needed)Git branch: mainSetup needed: Git repo detected; initialize Heddle with heddle initNext  command: heddle init

Two repository modes

Everything in the CLI dispatches on one question: who owns source authority. It is worth internalising before you pick a command.

Git Overlay

Entered with heddle init in an existing checkout. The real .git stays authoritative and owns commits, refs, packs, the index and worktree state. .heddle is a sidecar holding captures, provenance, threads, readiness, review, context and discussions. The extra heddle commit step exists only here. Removing .heddle leaves Git exactly as it was.

Native Heddle

Entered deliberately with heddle adopt. Heddle is the source authority; heddle capture alone saves source history and there is no commit step. The retained .git becomes an explicit Git Projection adapter. One-way.

Native Heddle is a legitimate destination, not an error state. If heddle doctor reports it when you expected Git Overlay, that is a different problem — see step 2.

1. Initialise Heddle in place

Run heddle init at the repo root. Heddle detects the existing .git/ directory and writes a sidecar at .heddle/. No flag controls this: the relationship to Git is what's on disk.

Adopt an existing Git repo

bash$ cd my-repo$ heddle initInitialized Heddle data in /Users/me/my-repo/.heddle for Git-overlay workflowsPrincipal: Anan <anan@heddle.sh> from git_configSide effects:  - created Heddle sidecar for the existing Git repository  - updated .git/info/exclude for Heddle metadata  - left Git-tracked files untouchedNext: heddle commit -m "..."

If you'd like to set the principal identity at init time, pass --principal-name and --principal-email. Otherwise Heddle reads them from your environment or git config on first capture.

Init with principal identity

bash$ heddle init --principal-name 'Anan' --principal-email anan@heddle.shInitialized Heddle data in /Users/me/my-repo/.heddle for Git-overlay workflows

2. Verify the install

heddle doctor prints a single-shot health report: repository mode, current thread, workspace counters, recommended next step. It's a good way to confirm Heddle is reading your repo correctly.

Confirm Heddle sees the repo as Git + Heddle

bash$ heddle doctorDoctor /Users/me/my-repoRepository: Git + HeddleThread: main [main checkout · clean]State: (initial)Changes: 0 modified, 0 added, 0 deletedWorkspace: 1 thread(s), 0 parallel, 0 ready, 0 blocked, 0 actor(s)Health: needs_attentionNext step: heddle ready --thread main

"Repository: Git + Heddle" is the line that confirms Git Overlay. If you expected that and it says Heddle native instead, Heddle did not see the .git/ directory — usually because init ran in the wrong location. (Native Heddle reached deliberately via adopt is a different thing entirely; see below.) The "Health" line reports needs_attention until you take a first save; that is expected on a freshly initialised repo.

3. Confirm the Git round trip

In Git Overlay there is nothing to set up between Heddle and Git — no mirror, no initialisation step, and no dependency on the git executable, since Heddle embeds its own engine. The round trip is capture → commit → push, and heddle verify is the command that says whether Heddle, the Git mapping, the worktree and the remotes currently agree.

Ask for the proof rather than assuming it

bash$ heddle verify# exits nonzero until every check is clean

For the full picture of getting work out to Git-only teammates — and what they do not receive — see Getting work back to Git.

4. Take a first capture

The atomic unit of work in Heddle is the capture. Make any change to the working tree, then capture it:

Make a change and capture the result

bash# edit a file in your repo$ heddle capture --intent "trace harness wiring"Captured state hd-9b1kr3xxdsn2 (cc3e3a34)Saved by: Anan <anan@heddle.sh>Next: heddle commit -m "..."

The state ID (hd-9b1kr3xxdsn2) is a fresh random ChangeId, minted per capture: even two captures with identical content get different IDs. The parenthesized value (cc3e3a34) is the separate content hash of the captured tree. See captures and states for the foundational concepts; see heddle capture for the full flag surface (intent, confidence, agent overrides, splits).

Backing out of Git Overlay

In Git Overlay, Heddle never touches your Git history or tracked files; its only write under .git/ is the .git/info/exclude entry that keeps the overlay out of Git's sight. The overlay itself is self-contained in .heddle/. If you decide it's not for you:

Remove the Heddle overlay — Git is unaffected

bash$ rm -rf .heddle

Your Git history, branches, and remotes are untouched. The Heddle record is gone, but the code Git knew about is exactly where it was.

This paragraph does not apply after heddle adopt. Once Heddle holds source authority, deleting .heddle deletes the authoritative history.

If you really do want Native Heddle

heddle adopt is the command the title of this page names, and it is deliberately the last thing on it. Verbatim from its own help: Git Overlay is the normal existing-Git mode: Git keeps source objects, refs, index, and worktree state while Heddle stores metadata in .heddle. adopt imports history and moves source authority to Heddle. And: Adoption is not required for normal Git Overlay use.

Afterwards, heddle capture alone saves source history — there is no commit step — and .git is retained for explicit Git Projection. --ref scopes what comes across; repeat it for selected branches or tags, or omit it to adopt everything.

The binary's own examples, verbatim

bash# adopt all local Git refs into native Heddle storage$ heddle adopt# adopt one branch or tag$ heddle adopt --ref main# adopt selected refs in another repo$ heddle adopt ../repo --ref main --ref v1.0

Next

Now that the repo is adopted, the natural next steps:

• Task threads: the pillar concept; one read makes the rest of Heddle click.
• Reviewing a task once you have a thread worth signing.
• Getting work back to Git: commit and push in Git Overlay, export git in Native Heddle, and what a Git-only collaborator does not receive.
• heddle adopt: the reference page for the one-way move.