Heddle: version control for agent work

the record

The versioned memory layer your agents always needed. What one agent learns, the next one remembers.

Lukehuman Mochiagent Atlasagent Juniperagent

Git
compatible

One thread
per agent

Reversible
history

Annotations as
versioned memory

open-source cli · public alpha

Version control
for agent work.

When agents write the code, your version control has to keep up. Heddle gives every agent its own isolated thread, makes your whole history undoable, and writes straight through to the Git repo you already have. No lock-in.

~/heddle · status

$ heddle status
Heddle status for main
Repository: Git + Heddle
Verification: 1 Git worktree path(s) have uncommitted changes

Thread: main
Verdict: work in progress
  checkout health needs attention
Saved change: hd-9h82p53w3s51
Change message: docs: add 0.5.0 changelog entry (#786)

Worktree
Checkout: Git branch checkout
Lifecycle: active

Changed paths: 1
Work in progress
  - Worktree: 1 Git worktree path(s) have uncommitted changes

Next
  command: heddle commit -m "..."
  why: there are uncommitted worktree changes; commit captures them and writes the matching Git commit
  then: run `heddle push` when the Git commit is ready to publish

the core loop

Git records what changed. Heddle records who, why, and what failed.

Every pass records who acted (signed attribution), why (an annotation the next agent reads before it edits), and what failed (a wrong approach turned into a guardrail). Each task runs on its own isolated thread, so parallel agents never collide.

~/work/api · core loop

$ heddle init

Initialized Heddle data in .heddle for Git-overlay workflows
Side effects:
  - created Heddle sidecar for the existing Git repository
  - updated .git/info/exclude for Heddle metadata
  - left Git-tracked files untouched

$ heddle status

Heddle status
Repository: Git + Heddle
Verification: clean
Thread: main (in sync with Git)
Next: open an isolated thread with heddle start <name>

$ heddle start feature/auth

Started isolated thread feature/auth
  (Heddle-managed checkout, no .git directory)

$ heddle commit -m 'wire reconnect into sync loop'

Committed hd-5aqcfrwvcs7d as Git commit 711ec9de
Saved by: Luke <luke@heddle.sh>
Agent: anthropic/claude-opus-4-8
Included: crates/grpc_hosted/src/sync.rs
Verification: clean

$ heddle context set --kind invariant

--kind invariant --scope symbol:reconnect -m "…"
Annotated …/grpc_hosted/sync.rs (1 active annotation)
  stored in .heddle/ · injected on PreToolUse

$ heddle land --thread feature/auth

Landing thread feature/auth → main
  body-only edits merged · signature change surfaced for review
  semantic 3-way merge, AST-aware

01 · init

Set up beside Git.

heddle init writes a .heddle/ sidecar next to .git/. It never rewrites history and never touches your tracked files. Git commits stay in Git; walk away byte-identical whenever you want.

additive · your Git history stays untouched

created.heddle/ sidecar

git historyuntouched

tracked filesuntouched

02 · status

See where you stand.

heddle status is observe-only. It reads your repo and recommends the next step. Nothing is written, nothing uploaded, history untouched.

read-only · safe to run anytime

.heddle/≈.git/

heddle start≈git worktree

heddle land≈git merge

heddle status≈git status

03 · start

Branch an isolated thread.

heddle start spins up a copy-on-write, Heddle-managed checkout, one per task or agent. Point a model at it and it never collides with main or another thread.

copy-on-write · no full clone

heddle thread list

* main           current
- feature/auth   ● isolated checkout
- refactor/db    ● isolated checkout

04 · commit

Signed, attributed, written through to Git.

Every authored state is a durable checkpoint, signed with ed25519 automatically, no key setup, and named for its author, human or agent. It writes straight through to your .git: a real Git commit, HEAD advances, plain git log shows it. No separate export.

attribution, not archaeology

statehd-5aqcfrwvcs7d

saved byLuke <luke@heddle.sh>

signatureed25519 · verified

05 · annotate

The next agent reads it before it edits.

Annotations are versioned objects (constraint, invariant, rationale) attached to a symbol and injected into the agent's context before it edits. Failed attempts become future guardrails.

travels into Claude Code on PreToolUse

heddle context get

--- [invariant] hd-zabjx94g3 (active) ---
by: Luke (via anthropic/claude-opus-4-8)
Reconnect must hold the session lock;
racing reconnects corrupt the stream cursor.

06 · land

Land semantically.

Heddle merges body-only changes cleanly and surfaces a signature change for review, because a contract change deserves a human. Then it lands back to main.

AST-aware 3-way · falls back to text hunks honestly

why it compounds

Isolated threads.
Memory that travels.

Two ideas do the heavy lifting. Every task runs in its own copy-on-write thread, and what each agent learns gets written into the code so the next one inherits it.

copy-on-write threads

Every task gets its own checkout.

heddle start spins up an isolated, Heddle-managed checkout: copy-on-write, no full clone, no .git of its own. Point one agent at feature/auth and another at refactor/db and they never touch the same files or stack onto each other's half-finished work. Parallel agents stop colliding, and any thread can be thrown away without a trace.

heddle start feature/auth

$ heddle start feature/auth
Started isolated thread feature/auth
  (Heddle-managed checkout, no .git directory)

$ heddle thread list
Current
* main           current
Other threads
- feature/auth   ● isolated checkout
- refactor/db    ● isolated checkout

embedded annotations

What one agent learns, the next one reads.

An annotation is a versioned note (invariant, constraint, rationale) pinned to a symbol or line and injected into the agent's context before it edits. For you: the reasoning behind a gnarly function stops living in one person's head. For the agent: last week's failed approach becomes this week's guardrail instead of a repeated mistake. And heddle context check tells you the moment an annotation goes stale because the code moved out from under it.