Heddle

Heddle is the everyday version control for humans and agents. It runs in your existing Git repository with no migration. Git remains first-class for storage, hosting, CI, and teammates using plain git; capture, review, ready, and land decisions happen in Heddle Threads, with Git history as their faithful projection. Raw Git remains an escape hatch, not a second workflow. The Rust CLI adds:

• thread-first agent workflows (lightweight named work units with lifecycle, freshness, and promotion semantics)
• local captures with automatic Git-compatible checkpoints and explicit human and agent attribution
• content-addressed immutable history with stable change identifiers that survive rewrites
• provenance-aware inspection (heddle query --attribution, heddle show, heddle diff)
• operation-agnostic recovery (heddle continue / heddle abort) without per-command lifecycle flags
• separate coordination surfaces for writer leases (heddle agent) and acting-worker context (heddle agent presence)
• explicit maintenance and interoperability namespaces (heddle maintenance, heddle bridge git)

cargo install heddle-cli
cd /path/to/your/git/repo
heddle status              # inspect Git safely; Heddle prints the exact next command
heddle init                # add Heddle metadata; Git remains the source store
heddle verify

This repository ships the OSS CLI. The hosted backend (weft) and the web product (tapestry) are separate, closed-source repositories — see Related projects.

What heddle does today

In a plain Git repo, observe-only commands do not create .heddle/. heddle status first reports:

• the current Git branch
• dirty worktree/index state
• whether Heddle has been initialized
• the exact next command to initialize Git Overlay

Run the exact command printed by heddle status. In an existing Git checkout, that is heddle init: it creates the .heddle sidecar while the real .git remains authoritative for commits, trees, refs, packs, index, and worktree state. Heddle stores captures, threads, provenance, discussions, and source mappings in .heddle. Those are a native Heddle feature: they travel over heddle push / heddle pull to a Heddle remote, and are deliberately not projected into Git. In a Git Overlay repository, context annotations (heddle context) and discussions (heddle discuss) are therefore local to that working copy — a collaborator who git clones the repository receives the source history and no Heddle store at all. Its embedded Sley engine powers the thin Git surface — clone, capture, pull, push, and remote — directly against .git. Heddle never requires the git executable or retains a second object warehouse at .heddle/git; explicit projection composes reconstructable state with Raw Git Object Residuals.

heddle import local atomically imports selected Git refs, makes Heddle the source authority, and enables the full Native Heddle feature set. The retained .git is then an explicit Git Projection adapter. Adoption is not required for normal Git Overlay use.

Heddle's CLI follows five operating principles — verification, disposability, composability, restraint, honesty — documented in docs/PRINCIPLES.md.

Capability status

Shipped

• Content-addressed immutable state model
• Stable change identifiers
• Threads and markers
• Explicit principal and agent attribution
• Provenance-backed local blame with rewrite preservation across snapshot, collapse, and merge flows
• Semantic diff and compare
• Semantic integration by default: ready, land, and sync use AST-item-level merge within a file when built with the default semantic feature (first-class Rust/Python/JS/TS; Go/C/C++/Java opt-in); the engine does not auto-rewrite cross-file imports or call-sites
• Automatic state signing: device-local ed25519 identity minted on first use signs every authored state — provenance with no manual key setup
• Git overlay: direct .git integration, explicit native adoption, import, export, sync
• Byte-identical Git round-trip, CI-enforced: import local→export reproduces identical commit/tree/blob/tag SHAs and a valid Git object graph, gated per-PR by 10 deterministic fixtures
• Multi-agent worktrees and agent registry

Foundation in place

• Hosted runtime (heddle-cli's optional client feature enables its internal native Iroh/session/provider implementation; weft-client-shim remains a non-optional, patchable extension contract)
• Verification and verification metadata across the wire protocol
• Commit-level visibility tiers: per-state StateVisibility records and heddle visibility set/promote verbs (with oplog tier records) are shipped client-side; Git projection visibility gating for exports and checkouts is landing; hosted serve-side enforcement is in progress

Planned

• First-class history graph UX in the CLI
• Partial clone and lazy object retrieval

The current compatibility promise and surfaces that remain unstable until 1.0 live in docs/STABILITY.md.

Installation

From crates.io

cargo install heddle-cli

The default feature set is git-overlay, native, local, semantic, zstd. To build a Git projection-only or native-only flavor, pass --no-default-features --features git-overlay or --no-default-features --features native.

From source

Obtain a source checkout from the release archive or with any Git-compatible client, then install it locally:

cd heddle
cargo install --path crates/cli

The client used to obtain the source is optional; Heddle itself does not invoke or require it.

Prerequisites: Rust 1.85+, cargo, rustfmt, clippy.

Getting Started

New to Heddle? In an existing Git checkout, start with heddle status and initialize the Git Overlay sidecar:

heddle status
heddle init
heddle capture -m "start project"
heddle push

For a new or unborn repo, initialize once, set attribution if needed, then use heddle capture as the Heddle save boundary:

heddle init --principal-name "Ada Lovelace" --principal-email [email protected]
heddle capture -m "start project"

In a Git checkout, heddle init creates the Heddle sidecar and leaves source storage in the checkout's real .git. heddle capture saves Heddle metadata and provenance in .heddle and writes the matching Git checkpoint through Sley as one operation. pull, push, and remote also use Sley directly. A capture includes the complete worktree and replaces the Git index with that tree. Use heddle import local when you want an atomic transition to Heddle-native source authority and its full feature set.

The verb-by-verb tour

# In an ordinary Git repo: inspect, initialize Git Overlay, and verify
heddle status
heddle init
heddle verify

# Save one attributed state and its Git Overlay checkpoint
heddle capture -m "add user authentication"

# Start isolated work and prove it is ready
heddle start feature/auth --path ../feature-auth
cd ../feature-auth
heddle capture -m "add auth validation"
heddle ready

# Land locally, then publish with the source authority
heddle land --thread feature/auth
heddle push

# Inspect, continue, or abort any in-progress integration
heddle status
heddle resolve --list
heddle continue   # or: heddle abort

# Inspect history and provenance
heddle log
heddle diff HEAD~1 HEAD
heddle query --attribution path/to/file.rs

# Inspect acting-worker context separately from writer authority
heddle agent presence list

# Run advanced integrity and Git projection operations
heddle maintenance fsck --full
heddle bridge git export --destination ../project.git

heddle status reports the current branch or thread, what is dirty, whether another operation is in progress, and the recommended next command. The same recommended_action field is carried through heddle doctor, heddle thread show, and heddle status for programmatic use.

heddle agent presence reports attribution and active-work context without granting write authority; lease-backed mutations remain under heddle agent. Repository integrity checks live under heddle maintenance fsck, while explicit Git import/export lives under heddle bridge git. These namespaces keep operational plumbing available without expanding the everyday verb surface.

In Git-overlay repositories, heddle land projects a landed thread as one atomic Git commit by default. The original per-State captures remain in Heddle history. Use heddle land --no-squash for a single invocation that should export one Git commit per State.

Core concepts

Concept	Description
State	Immutable snapshot of a repository at a point in time
ChangeId	Rewrite-stable logical change identifier (hc-…). It is carried forward across rewrites, but is not yet accepted as a command argument (see Identifiers in output)
ContentHash	BLAKE3 hash of object contents for integrity and deduplication
Thread	Mutable named reference to a state
Marker	Immutable named reference to a state
Principal	Human identity accountable for a change
Agent	Model identity associated with a change

Identifiers in output

History commands render distinct identifiers. They are not interchangeable:

• hs-… State ID — identifies one immutable state. A rewrite creates a new State ID, so the old ID still names the state before the rewrite. Heddle commands that accept a state identifier use this ID; unambiguous prefixes can be used where supported.
• hc-… ChangeId — the logical identifier carried forward across rewrites. It identifies the continuing change, but is not yet usable as a command argument.
• (……) content hash (for example, (61408ef9), shown by heddle log --verbose and heddle show) — a short BLAKE3 digest of the state's contents. It is not a Git commit SHA or a command argument.
• Git checkpoint SHA (shown on the Git checkpoint: line by heddle log --verbose and heddle show) — the Git commit that binds the state into Git history for Git-compatible clients.

Rule of thumb: use hs-… State IDs with Heddle commands and checkpoint SHAs with Git-compatible clients. The rewrite-stable hc-… ChangeId is not yet usable as a command argument.

Agent-friendly output

Heddle is designed for programmatic use by agents and automation. Text is always the default, including when stdout is piped. Pass --output json for the full machine contract or --output json-compact for the smaller decision surface:

heddle status --output json
heddle doctor --output json
heddle diff --output json
heddle log --output json
heddle show HEAD --output json

See .agents/agent-workflows.md for durable automation guidance.

For idempotent retries, inspect heddle help --output json before using --op-id or HEDDLE_OPERATION_ID. Commands with supports_op_id: true support caller-supplied explicit replay: the same id plus the same arguments replays the recorded outcome, while the same id with different arguments fails with a typed conflict. persists_op_id is reserved for commands that generate and save an id across interrupted retry loops; current replay-safe automation should supply an explicit UUID. --op-id is intentionally not advertised as a broad global option in the command catalog; use each command's op_id_behavior field.

Configuration

Heddle uses three local config scopes:

• UserConfig (~/.config/heddle/config.toml) — user identity, agent defaults, output preferences, hosted-client credentials
• RepoConfig (.heddle/config.toml) — repository source authority, local behavior, ignore defaults, storage coordinates, remote aliases, repository format version
• WorktreeState — per-checkout runtime state (current session, segment) tracked separately from repo config

Set [land] squash = false in user config to make heddle land preserve per-State Git export by default. The command-line --no-squash flag provides the same opt-out for one land operation.

Precedence: CLI flags override the relevant config scope; env vars override file-backed config where supported; repo config stays repo-local; worktree state stays checkout-local.

Useful environment variables:

export HEDDLE_AGENT_PROVIDER="anthropic"
export HEDDLE_AGENT_MODEL="claude-opus-4-7"
export HEDDLE_PRINCIPAL_NAME="Your Name"
export HEDDLE_PRINCIPAL_EMAIL="[email protected]"

export RUST_LOG=heddle=debug
export RUST_BACKTRACE=1

Heddle records the agent model string verbatim and echoes it back in attribution output (for example the Agent: line of heddle log --verbose). If the coding agent reports a model id with a bracketed suffix — such as claude-opus-4-8[1m] — heddle preserves the suffix as-is; it does not add or interpret it. The suffix is supplied by the agent harness to distinguish a model variant (for Claude models the bracketed tag denotes the context-window variant), so set HEDDLE_AGENT_MODEL to whatever identifier you want recorded.

Optional OpenTelemetry command tracing, its privacy boundary, and pilot collector wiring are documented in CLI trace export.

Repository layout

This repository is a Cargo workspace. The OSS crates live under crates/:

crates/cli/                 # the `heddle` binary and command dispatch
crates/cli-args/            # clap argument surface
crates/cli-contract/        # verb catalog, schemas, help, recovery contracts
crates/cli-render/          # human-facing terminal presentation
crates/config/              # user-config TOML schema, credentials, tracing init
crates/verbs/               # embeddable verb facade: status/diff/merge/save plans
crates/hosted-client/       # hosted transport, identity, credentials, and sync
crates/agent-relay/         # harness event relay and agent coordination adapter
crates/objects/             # core object and repository model
crates/repo/                # repository helpers and higher-level repo operations
crates/refs/                # threads, markers, HEAD, packed refs
crates/oplog/               # undo/redo oplog model
crates/semantic/            # semantic diff and code-aware analysis
crates/merge/               # merge core
crates/state-review/        # state-level review helpers
crates/ingest/              # `heddle-ingest` binary and Git import path
crates/wire/                # native Heddle wire protocol types
crates/crypto/              # crypto primitives
crates/devtools/            # developer tooling
crates/mount/               # filesystem mount support
crates/git-projection/      # Git import, export, and projection engine

docs/                       # architecture, principles, stability, design notes
specs/                      # Quint formal specifications
tests/                      # integration and property tests

The net-new hosted protobuf contract and generated SDK sources are owned by the public HeddleCo/api repository. The target packages are heddle-api and @heddleco/api, but their coordinated Heddle, Weft, and Tapestry cutover is still blocked; see ADR 0048. Heddle keeps native CLI and daemon behavior internal when it does not require a cross-product contract.

Architecture and runtime details are in docs/ARCHITECTURE.md.

Development

cargo build
cargo test --workspace
cargo clippy -- -D warnings
cargo fmt --check

cargo test --workspace runs every non-ignored, default-feature Rust test in the workspace. Feature-gated and external-service suites are listed in .agents/testing.md.

Contributor rules and documentation truth guidance are in AGENTS.md.

Related projects

Heddle is one of three repositories under HeddleCo:

• HeddleCo/heddle (this repo) — the OSS CLI, Apache-2.0
• HeddleCo/weft — closed-source hosted backend that provides hosted namespaces, repositories, grants, and the server side of the wire protocol that heddle's client feature talks to
• HeddleCo/tapestry — closed-source SvelteKit marketing site and hosted web app

The hosted control plane, web UI, and any "hosted X" surfaces live in weft and tapestry. This repository contains only the OSS CLI and its supporting crates.

License

Licensed under the Apache License, Version 2.0. See LICENSE.

---

Heddle is still alpha software. Storage formats, APIs, and the wire protocol are evolving quickly.