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. Heddle aligns its main thread with the existing Git history, which you bring in with the bridge's import step.

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 the Git-overlay mode worked. If it instead says "Heddle native," Heddle didn't see the .git/ directory, usually because you ran init in the wrong location. The "Health" line reports needs_attention until you take a first save; that's expected on a freshly adopted repo.

3. Inspect the bridge

The Heddle ↔ Git bridge is what lets you eventually round-trip work back to Git commits. Check the bridge state with heddle bridge git status:

Bridge state on a freshly adopted repo

bash$ heddle bridge git statusMirror: /Users/me/my-repo/.heddle/git (not initialized yet)Git import: in syncGit overlay health: Git overlay and Heddle agree

The mirror at .heddle/git/ isn't initialised yet; that's fine. You'll only need it when you start exporting Heddle states back to Git as commits. For now, "Git import: in sync" means nothing in your Git history is waiting to be ingested into Heddle.

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 checkpoint -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).

A note on cleanup

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.

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.
• Bridging back to Git: when you're ready to push a signed thread as a Git commit.