{"slug": "show-hn-heddle-content-addressed-contracts-for-spec-driven-agent-loops", "title": "Show HN: Heddle, content-addressed contracts for spec-driven agent loops", "summary": "Heddle, a new open-source tool, treats software units as content-addressed contracts rather than files, enabling agent loops to reuse verification, compute blast radius precisely, and regenerate code from a few hundred tokens of context. The tool reduces context token usage by 5.5x in benchmarks by caching test results and providing mechanical dependency tracking. Heddle is available via pip and integrates with Claude Code through MCP.", "body_md": "**Heddle treats software units as content-addressed contracts rather than files.** An MCP server that makes agent regeneration loops cheap.\n\nBecause contracts are content-addressed and dependency-aware, agents reuse verification, compute blast radius precisely, and regenerate code from a few hundred tokens of context instead of re-reading whole files. Build systems ask which files changed. Heddle asks which software obligations changed.\n\nThe heddle is the part of a loom that holds the warp threads, the fixed, durable strands, while the shuttle weaves disposable weft through them. **Contracts are warp. Code is weft.**\n\nAgents repeatedly pay to rediscover software structure. Spec-driven development tools made specs the durable artifact and code regenerable, but they run on plain files, so every regeneration loop re-derives what the project already knows:\n\n**Context acquisition is expensive.** Regenerating one unit means re-reading whole spec and source files: thousands of tokens to learn what a few hundred convey.**Verification is uncached.** Every regeneration re-runs (and re-reads the output of) the full relevant test surface, even for units whose contracts haven't changed.**Blast radius is by convention, not mechanism.** When a spec changes, nothing tells the agent precisely which dependents are invalidated.\n\nHeddle treats each software unit as a content-addressed contract with explicit dependencies, not a file. A contract is a small YAML spec (signature, invariants, examples, dependency names); the implementation behind it is regenerable weft. Because every contract is hashed and its dependencies are named, the structure an agent keeps re-deriving from files becomes something heddle computes once and serves.\n\nThe model buys three things, all mechanical:\n\n**Verification caching.** A green test result is keyed on the contract, implementation, and dependency hashes, and served from cache until one of them changes. pytest runs only on a real miss.**Mechanical blast radius.** A contract change reports the exact set of invalidated dependents, transitively and by hash, not by convention.**Tiny context packets.** An agent regenerating a unit gets the contract, its dependencies' signatures, and its callers as one packet of a few hundred tokens, instead of the whole file closure.\n\nSame three regeneration tasks on a 20-contract sample project, once with raw file reads, once through heddle (tiktoken cl100k, reproduce with `uv run python bench/benchmark.py`\n\n):\n\n| task | raw files | heddle | reduction |\n|---|---|---|---|\n| revenue_by_region | 1,925 | 371 | 5.2x |\n| top_customers | 2,137 | 334 | 6.4x |\n| revenue_by_category | 1,942 | 392 | 5.0x |\ntotal |\n6,004 |\n1,097 |\n5.5x |\n\nRaw mode counts what a file-based agent reads per task: the unit's spec file, every transitive dep's spec file, every source module in the dep closure, the unit's test file, and the output of running the suite. It is deliberately generous to the baseline: it assumes the agent already knows the exact dependency closure, which is precisely the thing heddle computes for you.\n\n```\npip install heddle-mcp\n# or from source: pip install \"git+https://github.com/davet47/heddle\"\n\ncd your-project\nheddle init                 # creates .heddle/ and contracts/\nheddle index                # builds the store from contracts/\n```\n\nPoint Claude Code at it:\n\n```\nclaude mcp add heddle -- heddle serve\n```\n\n(Stdio transport; the server resolves the project by walking up from its working directory to the nearest `.heddle/`\n\n.)\n\nOne YAML file per unit in `contracts/`\n\n. Minimal, hand-writable, hashable:\n\n``` php\nname: revenue_by_region\nsignature: \"(sales: list[Sale]) -> dict[Region, float]\"\ndeps: [Sale, Region]            # other contract names\ninvariants:\n  - excludes sales where completed is false\n  - excludes sales with null amount\nexamples:\n  - in:  \"[Sale(region='QLD', amount=10, completed=True)]\"\n    out: \"{'QLD': 10.0}\"\ntests: [tests/test_revenue.py::test_revenue_by_region]   # pytest node IDs\nimpl: src/revenue.py::revenue_by_region                  # current woven weft\n```\n\nSubdirectories are namespaces: `contracts/billing/invoice.yaml`\n\nis the contract\n`billing/invoice`\n\n, so the same short name can live in different folders. A\ncontract's `name`\n\nmust match its path under `contracts/`\n\n.\n\nA contract belongs on a stable seam: an interface other units depend on and that you expect to outlive its current implementation. The implementation behind it is disposable weft, regenerated freely. Dropping a contract where it does not earn that place is correct use, not a failure. The failure mode is the opposite, over-pinning interiors you would happily rewrite, which turns the durable layer into busywork.\n\nContracts are reviewed artifacts. Authoring one is cheap and getting cheaper, so the real cost is reviewing it, not writing it. A wrong contract is worse than no contract, because the durable artifact now lies: agents will regenerate code to satisfy a spec that is itself incorrect. Review a contract the way you review an interface, not the way you skim generated code.\n\n**Contract hash**: sha256 over a canonical form: keys sorted, whitespace normalised, comments stripped, invariant and example order preserved, dep order ignored.`impl`\n\nand`tests`\n\nare excluded, so**relocating files never invalidates.** Invariants are free text and live inside this hash, so rewording one without changing its meaning still moves the contract hash and re-verifies every dependent. Behaviour-equivalent prose edits are not free yet (see[Roadmap](https://github.com/davet47/heddle/blob/main/ROADMAP.md)).**Impl hash**: sha256 over the normalised AST of the implementation, so reformatting and comment edits never bust the cache. Docstrings are stripped too.**Verification key**:`(contract hash, impl hash, transitive dep contract hashes)`\n\n. Heddle caches verification results, not correctness: a cached green result is served iff the full key matches, and an edit to any contract in the closure forces a re-run. Failures are never served from cache. Two caveats are worth knowing. A cached pass assumes deterministic tests, so a green result that depended on wall-clock time, network, or randomness can outlive the condition that made it pass. And test source is not yet part of the key, so editing a test body without touching the contract or impl does not by itself force a re-run (see[Roadmap](/davet47/heddle/blob/main/ROADMAP.md)).\n\n| tool | does |\n|---|---|\n`get_contract` |\nthe ~300-token context packet: contract + hash + one-line dep signatures + caller list |\n`put_contract` |\nvalidate, write `contracts/<name>.yaml` , return new hash + every invalidated dependent |\n`get_dependents` |\nblast-radius query, direct or transitive, names + hashes |\n`verify` |\nper-unit `cached-pass` / `pass` / `fail` ; runs pytest only on cache misses; failures come back as a ≤40-token assertion summary, never a traceback |\n`status` |\ndirty contracts, stale verifications, cache hit-rate, resolved verify interpreter, cumulative token counters |\n\nEvery tool returns structured errors — `{\"error\": {\"code\": \"unknown_dep\", \"message\": \"'Regoin' not found — nearest: 'Region'\"}}`\n\n— never a stack trace.\n\n`verify`\n\nruns your tests with the project's own python, resolved in order:\n`heddle serve --python PATH`\n\n→ `.heddle/config.json`\n\n(`{\"python\": \"...\"}`\n\n) → an\nauto-detected `<project>/.venv`\n\n→ the interpreter running heddle. So a\nglobally-installed heddle can verify a project against its own virtualenv without\nbeing installed into it; `heddle status`\n\nshows which interpreter it resolved.\n\n`.heddle/config.json`\n\nalso takes `verify_timeout`\n\n(seconds per pytest run,\ndefault 300) for suites that need longer than the default, and `pycache_trust`\n\n(default `true`\n\n); set `pycache_trust: false`\n\n— or pass `--no-pycache-trust`\n\n— to\nclear the project's `__pycache__`\n\nbefore each verify run, so a stale `.pyc`\n\ncan\nnever shadow the current source.\n\n`heddle init`\n\n· `heddle index`\n\n· `heddle serve`\n\n· `heddle status`\n\n· `heddle verify`\n\n. The sqlite store under `.heddle/`\n\nis derived state: delete it any time and `heddle index`\n\nrebuilds it from `contracts/`\n\n.\n\n`heddle verify <name>…`\n\nruns the same cached verification as the MCP tool from the command line and exits nonzero if any unit fails — drop it in CI or a pre-commit hook.\n\n```\ncd examples/sales\nheddle init && heddle index && heddle serve   # then point your agent at it\n```\n\n20 contracts, 25 tests, three dependency layers deep.\n\n```\nuv sync\nuv run pytest             # full suite; hash stability is the load-bearing suite\nuv run python bench/benchmark.py\n```\n\nPython-only and single-process by design for v0.1. Everything not in this README is an [issue](/davet47/heddle/blob/main/ISSUES.md).\n\nApache 2.0", "url": "https://wpnews.pro/news/show-hn-heddle-content-addressed-contracts-for-spec-driven-agent-loops", "canonical_source": "https://github.com/davet47/heddle", "published_at": "2026-06-24 09:33:07+00:00", "updated_at": "2026-06-24 09:44:32.386830+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "large-language-models"], "entities": ["Heddle", "Claude Code", "MCP", "pytest", "GitHub"], "alternates": {"html": "https://wpnews.pro/news/show-hn-heddle-content-addressed-contracts-for-spec-driven-agent-loops", "markdown": "https://wpnews.pro/news/show-hn-heddle-content-addressed-contracts-for-spec-driven-agent-loops.md", "text": "https://wpnews.pro/news/show-hn-heddle-content-addressed-contracts-for-spec-driven-agent-loops.txt", "jsonld": "https://wpnews.pro/news/show-hn-heddle-content-addressed-contracts-for-spec-driven-agent-loops.jsonld"}}