Git overlay

Why an overlay

The honest answer: because Git won and we know it. Replacing Git is a 10-year project even if your protocol is better; Heddle's bet is that you don't have to replace Git to add what Git is missing. The overlay sits underneath your existing workflow — your GitHub PRs, your CI, your code-host integrations — and adds the agent-work record on top.

Concretely: a repo with Heddle initialised is still a Git repo. git status works. git push works. Your team members who haven't installed Heddle keep working in Git, none the wiser. The Heddle data is in .heddle/ — additive, opt-in, ignorable.

Adopt mode

The default. heddle init in an existing Git repo enters adopt mode: Heddle reads the current branch, treats it as the main thread, and starts recording captures from here forward. The Git history before this point is preserved untouched and visible from Heddle as a single starting state.

Adopt an existing Git repo

bash$ cd my-repo$ heddle initinitialized · git-overlay mode · adopted main  main thread mapped to git ref refs/heads/main

Standalone mode

For new repos that don't need Git, heddle init --git-overlay none initialises a standalone Heddle repo. No .git/ directory is created, no Git semantics apply. The repo can be bridged to Git later if needed — heddle bridge git init writes the bridge metadata against an existing Git remote.

The bridge

heddle bridge git is the surface that moves work between Heddle and Git. It's two-way:

• Export. heddle bridge git export <thread> takes the resolved state of a thread and writes it as a single Git commit on the bridged branch. The commit message is the task name, the body summarises the captures, the signature lands in a trailer.
• Import. heddle bridge git import brings external Git commits in as adopted captures. Useful when a teammate without Heddle pushes work to the same branch.
• Status. heddle bridge git status shows the relationship between Heddle's threads and the bridged Git refs — what's exported, what's pending, what's diverged.

What lives where

The honest mental model:

• .git/ — Git's storage. Commits, refs, packed objects. Heddle never modifies this directory; only the bridge reads/writes Git's plumbing, and only through standard porcelain.
• .heddle/ — Heddle's storage. Captures, states, threads, contexts, the oplog. Self- contained; you can blow it away with rm -rf .heddle and Git keeps working (you lose the Heddle record but not the code).
• The working tree — shared. Both Git and Heddle see the same files. A capture and a commit can both be taken from the same working tree; they record different things about it.

Round-trip semantics

A common workflow is "edit in Heddle, export to Git, push to GitHub, merge the PR, pull back." The round-trip is idempotent: a Heddle thread exported as a Git commit and then re-imported produces the same Heddle state ID it started with. Bridge ↔ Git ↔ remote ↔ Git ↔ bridge can cycle without drift.

Drift can happen if a Git-side rebase rewrites history that Heddle had already exported. The bridge detects this and surfaces it via heddle bridge git status with a recommended action. The recommended action is almost always "import the rewritten history as a new branch and pick what you want from each."

The commands

• heddle init — with optional --git-overlay mode flag.
• heddle bridge git — export, import, status.

Next: the oplog for what Heddle records about the bridge operations themselves, or namespaces for how multiple bridged repos compose into one organisational structure.