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 adopts the current HEAD as the starting state.

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 sidecar in /Users/me/my-repo/.heddle for Git-overlay workflows

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 sidecar 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 hybrid (Git-overlay)

bash$ heddle doctorDoctor /Users/me/my-repoRepository mode: git-overlay (git+heddle-sidecar)State: hd-d01a8b4e (b3a8e201)Changes: 0 modified, 0 added, 0 deletedWorkspace: 1 thread(s), 0 parallel, 0 ready, 0 blocked, 0 actor(s)Health: ok

"Repository mode: git-overlay (git+heddle-sidecar)" is the line that confirms the adopt-mode worked. If it instead says "native-heddle (heddle-native)," Heddle didn't see the .git/ directory — usually because you ran init in the wrong location.

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 statusRepository mode: git-overlay (git+heddle-sidecar)Mirror: .heddle/git (not initialized — run `heddle bridge init`)Git import: in sync

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-9a1c (b3a8e201)

The state ID (hd-9a1c) is content-addressed — two captures with identical content produce the same ID. 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 modifies .git/. The overlay 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.