Reduces agent context costs by treating software units as content-addressed contracts with verification caching and precise blast radius calculation.
Also known as davet47/hashloom
- Stars
- 2
- Tools
- 5
- Downloads, 30 days
- 204
- Latest version
- 0.6.0
- Last commit
- Sep 1, 2026
- License
- Apache-2.0
What is Hashloom MCP?
Hashloom reduces agent context costs by treating software units as content-addressed contracts with verification caching and precise blast radius calculation. It exposes 5 tools, such as get_contract, put_contract, get_dependents.
Summary generated from the project's README
About Hashloom MCP server
Developers using AI agents for software engineering can use Hashloom to reduce context costs and speed up regeneration loops. Instead of treating code as a collection of files, it treats software units as content-addressed contracts. This allows an agent to receive a tiny context packet of a few hundred tokens containing only the necessary signatures and dependencies, rather than re-reading entire files and losing thousands of tokens to redundant information.
By using the server via stdio transport, such as with Claude Code, the system provides mechanical blast radius calculation and verification caching. When a contract changes, the server identifies exactly which dependents are invalidated. It also caches test results based on the hashes of the contract, implementation, and dependencies, ensuring that tools like pytest only run when a genuine change occurs. This makes the development cycle more efficient by focusing only on what has actually changed.
What you can do with it
- 1Minimize agent context usageAn agent can regenerate a specific code unit using a small packet of tokens instead of reading the entire file closure.
- 2Calculate software blast radiusDetermine exactly which parts of a project are affected by a change to a specific contract.
- 3Optimize test executionRun tests only when the underlying contract or implementation has actually changed to save time.
- 4Enforce contract provenancePrevent the verification of code that relies on unreviewed or inferred contracts.
Written from the project's README. Every use case is checked against a quote from it.
How to install Hashloom MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Hashloom MCP in Claude Code
$ claude mcp add hashloom -- uvx hashloomInstall Hashloom MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"hashloom": {
"command": "uvx",
"args": [
"hashloom"
]
}
}
}Install Hashloom MCP in VS Code
.vscode/mcp.json
{
"servers": {
"hashloom": {
"type": "stdio",
"command": "uvx",
"args": [
"hashloom"
]
}
}
}Install Hashloom MCP in VS Code CLI
$ code --add-mcp '{"name":"hashloom","type":"stdio","command":"uvx","args":["hashloom"]}'Install Hashloom MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"hashloom": {
"command": "uvx",
"args": [
"hashloom"
]
}
}
}Install Hashloom MCP in Codex
$ codex mcp add hashloom -- uvx hashloomInstall Hashloom MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.hashloom] command = "uvx" args = ["hashloom"]
Install Hashloom MCP in Gemini CLI
$ gemini mcp add -s user hashloom uvx -- hashloomInstall Hashloom MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"hashloom": {
"command": "uvx",
"args": [
"hashloom"
]
}
}
}Hashloom MCP tools 5
Detected from the READMEget_contractput_contractget_dependentsverifystatus
| get_contract | — | |
| put_contract | — | |
| get_dependents | — | |
| verify | — | |
| status | — |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachabledavet47/hashloom is public and reachablegithub.com/davet47/hashloom ↗Pass
- Package names this repository as its sourcehashloom names davet47/hashloom as sourcepypi.org/project/hashloom/ ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for hashloompypi.org/project/hashloom/ ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-09-01github.com/davet47/hashloom ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from hashloomPass
- No critical advisory in the package or its dependencies41 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model5 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubhashloom

Hashloom treats software units as content-addressed contracts rather than files. An MCP server that makes agent regeneration loops cheap.
Because 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. Hashloom asks which software obligations changed.
The name is a coinage that says exactly what it is: a loom keyed by hashes. On a loom, the warp threads are the fixed, durable strands, and the shuttle weaves disposable weft through them. Contracts are warp. Code is weft. (Until 0.3.3 this project shipped as heddle-mcp; the engine is unchanged.)
The problem
Agents 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:
- 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.
The model
Hashloom 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 hashloom computes once and serves.
Outcomes
The model buys three things, all mechanical:
- 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.
The number
Same three regeneration tasks on a 20-contract sample project, once with raw file reads, once through hashloom (tiktoken cl100k, reproduce with uv run python bench/benchmark.py):
| task | raw files | hashloom | reduction |
|---|---|---|---|
| revenue_by_region | 1,925 | 369 | 5.2x |
| top_customers | 2,137 | 337 | 6.3x |
| revenue_by_category | 1,942 | 396 | 4.9x |
| total | 6,004 | 1,102 | 5.4x |
Raw 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 hashloom computes for you.
The same methodology sweeps every unit of all five example projects —
Python, Go, TypeScript, Java, and C# — via bench/sweep.py, and works on any hashloom
project including yours. Full sweeps average lower than the gate (they count
the leaf types that barely benefit); the ratio tracks dependency depth, so
deeper projects score higher. All the numbers, their distributions, and the
honest caveats live in docs/benchmarks.md.
Quickstart
pip install hashloom
# or from source: pip install "git+https://github.com/davet47/hashloom"
cd your-project
hashloom init # creates .hashloom/ and contracts/
hashloom index # builds the store from contracts/
Point Claude Code at it:
claude mcp add hashloom -- hashloom serve
(Stdio transport; the server resolves the project by walking up from its working directory to the nearest .hashloom/.)
New to the workflow? docs/getting-started.md walks through building a package contract-first with an agent — the working rules to give it, the review loop, and the verify gate.
Contracts
One YAML file per unit in contracts/. Minimal, hand-writable, hashable:
name: revenue_by_region
signature: "(sales: list[Sale]) -> dict[Region, float]"
deps: [Sale, Region] # other contract names
invariants:
- excludes sales where completed is false
- excludes sales with null amount
examples:
- in: "[Sale(region='QLD', amount=10, completed=True)]"
out: "{'QLD': 10.0}"
tests: [tests/test_revenue.py::test_revenue_by_region] # pytest node IDs
impl: src/revenue.py::revenue_by_region # current woven weft
status: inferred # reverse-engineered, not yet human-reviewed; omit once confirmed
Subdirectories are namespaces: contracts/billing/invoice.yaml is the contract
billing/invoice, so the same short name can live in different folders. A
contract's name must match its path under contracts/.
When to write a contract
A 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.
Contracts 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.
A contract an agent reverse-engineers from existing code can declare that it hasn't earned that review yet: status: inferred. Tools then flag — by default, never refuse — any blast-radius or verification answer that rests on it (inferred: true on dependents, an inferred list on verify results, a review queue in status). Teams that want unvetted contracts to hard-fail can opt in to strict provenance mode (.hashloom/config.json → {"strict_provenance": true}): verify then refuses such units with a structured inferred_contract error — no tests run, no verdict cached — until they're reviewed; reads and writes stay advisory so drafts can still land and be inspected. Absent means confirmed, and confirming an inferred contract after review is free: status is provenance, not meaning, so the flip invalidates nothing (under strict mode, a pre-existing green simply revives on confirm).
Hashing semantics
- Contract hash: sha256 over a canonical form: keys sorted, whitespace normalised, comments stripped, example order preserved, dep order ignored.
impl,tests,invariants, andstatusare excluded, so relocating files never invalidates, rewording an invariant is free, and confirming an inferred contract never invalidates anything. Invariants are documentation, not a machine obligation; the real check is the tests, whose source is in the verification key. - 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, test-source hash, toolchain identity, transitive dep contract hashes). Hashloom caches verification results, keyed so that a change to any contract in the closure, to the implementation, to a test's own source, or to the toolchain identity forces a re-run. The identity is the toolchain version (python 3.11.7,go 1.21.5,node <v> ts <v>,java 21.0.3,dotnet 9.0.303) plus, when the project commits a dependency source at its root (uv.lock,go.sum,package-lock.json,pom.xml, ...), adeps <file>=<hash>digest of it — so a green from an environment with a different declared dependency set is never trusted, and a 3.11 pass is never served to 3.13. The grain is the committed declared set (never OS/arch — CI greens still serve every platform); a venv that disagrees with its own lockfile is outside the key, which is one of the things shared-cache revocation exists for. Failures are never served from cache. For Python, the test-source hash covers each test's fixture closure too — the fixtures it requests (arguments,usefixtures, literalgetfixturevalue), autouse fixtures in scope, and fixtures of fixtures, statically resolved through the test's module and conftest chain (nearest wins) — so editing only a conftest fixture busts exactly the tests that lean on it; fixture use the static walk cannot resolve degrades to hashing the whole chain, over-busting rather than under-busting. Two caveats. 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 plain helper functions a test imports and calls (and non-Python test helpers) are still outside the hash — only the fixture graph is covered (see ISSUES.md).
MCP tools (the entire surface)
| tool | does |
|---|---|
get_contract |
the ~300-token context packet: contract + hash + one-line dep signatures + caller list |
put_contract |
validate, write contracts/<name>.yaml, return new hash, a semantic diff of what changed, and every invalidated dependent |
get_dependents |
blast-radius query, direct or transitive, names + hashes; inferred (unreviewed) contracts flagged |
verify |
per-unit cached-pass / pass / fail plus a top-level ok gate bit; radius=true widens each name to its full blast radius; runs tests only on cache misses; failures come back as a ≤40-token assertion summary, never a traceback; inferred contracts in the closure flagged (refused under strict provenance mode) |
status |
dirty contracts, stale verifications, cache hit-rate, resolved verify interpreter, cumulative token counters |
Every tool returns structured errors — {"error": {"code": "unknown_dep", "message": "'Regoin' not found — nearest: 'Region'"}} — never a stack trace.
The verify interpreter
verify runs your tests with the project's own python, resolved in order:
hashloom serve --python PATH → .hashloom/config.json ({"python": "..."}) → an
auto-detected <project>/.venv → the interpreter running hashloom. So a
globally-installed hashloom can verify a project against its own virtualenv without
being installed into it; hashloom status shows which interpreter it resolved.
.hashloom/config.json also takes verify_timeout (seconds per pytest run,
default 300) for suites that need longer than the default, pycache_trust
(default true); set pycache_trust: false — or pass --no-pycache-trust — to
clear the project's __pycache__ before each verify run, so a stale .pyc can
never shadow the current source, and strict_provenance (default false) to
make verify refuse units whose closure contains inferred contracts.
Beyond Python
The impl's file extension picks the language adapter — each brings a normalised-AST hasher and a test runner, so the same cosmetic-vs-meaning hashing semantics hold per language:
- Go (
.go): hashes via the stdlibgo/ast, runsgo test -json. Toolchain resolves like the interpreter:.hashloom/config.json{"go": "..."}, elsegoon PATH. - TypeScript (
.ts/.tsx/.mts/.cts): hashes via the target project's owntypescriptcompiler API, auto-detects the test runner frompackage.json(vitest / jest, else Node's built-innode:test). Needs Node= 22.6; config key
{"node": "..."}. - Java (
.java): hashes via a single-filejavac-tree helper (JDK-only, no dependencies), auto-detects the test runner from the build manifest —pom.xmlroutes to Maven,build.gradle/build.gradle.ktsto Gradle, and a committedmvnw/gradlewwrapper is preferred over the PATH binary. Needs a JDK >= 11 plus Maven or Gradle; config key{"java": "..."}. - C# (
.cs): hashes via a Roslyn token-stream helper that hashloom compiles once per SDK version with the SDK's owncscagainst its bundledMicrosoft.CodeAnalysis(no packages, no network), runsdotnet teston the root project/solution with aFullyQualifiedName~filter (xUnit, NUnit, and MSTest all ride it). A Microsoft.Testing.Platform project (xunit v3) works too, with one caveat:dotnet testignores the filter there, so each verify runs that project's whole suite — conservative (an unrelated failure blocks; a green still covers the contract's tests). Needs the .NET SDK >= 8; config key{"dotnet": "..."}.
Python stays the default; a project can mix languages freely.
Team-shared verification cache
By default the cache lives in your local .hashloom/store.db. Point it at a shared
backend and one green verify serves the whole team — CI verifies a unit once and
every teammate's agent gets cached-pass:
// .hashloom/config.json
{"shared": {"url": "https://cache.internal:8770", "token": "..."}}
Run the backend anywhere with python -m hashloom.cache_server (a small
bearer-token HTTP service over a SQLite store; an operational process, not a CLI
command). Auth is scoped: give the server an optional --publish-token and only
holders of it can write greens (CI publishes, laptops with the read token only
consume; a single token still grants both roles, as before). A read-only client
can set "publish": false to skip publish requests entirely. The server
handles requests concurrently, and duplicate publishes of the same
verification key are no-ops (first writer wins). Only greens are
published — failures never cross the boundary — and the toolchain-in-key rule
above keeps a shared green sound across machines. If the shared store is
unreachable, verify degrades silently to local.
CLI
hashloom init · hashloom index · hashloom serve · hashloom status · hashloom verify. The sqlite store under .hashloom/ is derived state: delete it any time and hashloom index rebuilds it from contracts/. It can't serve you stale answers either — if contracts/ on disk has drifted from the store (a git pull without a reindex), verify refuses the affected units with a structured stale_store error instead of serving verdicts keyed by old hashes, until you run hashloom index.
hashloom verify <name>… runs the same cached verification as the MCP tool from the command line and exits nonzero unless every unit is green (a failure, an unknown name, or an unverifiable unit all block) — drop it in CI or a pre-commit hook. --radius widens each name to itself plus every transitive dependent, so one command gates a change's whole blast radius: hashloom verify --radius Sale.
Try the sample project
cd examples/sales
hashloom init && hashloom index && hashloom serve # then point your agent at it
20 contracts, 25 tests, dependency chains up to six contracts deep. Every example directory ships its own README with per-language run instructions.
There are counterpart examples in four other languages, each using the same
init && index loop:
- Go —
examples/go-ledger: 8 contracts over a small double-entry ledger.hashloom verify --radius Entrygates the blast radius withgo testunder the hood. Needs a Go toolchain. - TypeScript —
examples/ts-cart: 8 contracts over a shopping cart. Runnpm installfirst for itstypescript; verification runs on Node's built-innode:test. Needs Node >= 22.6. - Java —
examples/java-payroll: 11 contracts over a weekly payroll run, three layers deep — records,Class.methodquals, a parameterized bracket table, and a@Nestedtest class with dotted node ids; the shape of a Spring service layer with zero framework dependencies.hashloom verify --radius TimeSheetruns Maven under the hood. Needs a JDK >= 17 and Maven. - C# —
examples/csharp-invoices: 11 contracts over a billing run, the Java example's three-layer shape in C# idiom — records hashed whole,Class.Methodquals, an[InlineData]bracket table, and a nested test class with dotted node ids (the runtime'sOuter+Innerspelling).hashloom verify --radius DiscountCentsrunsdotnet testunder the hood. Needs the .NET SDK >= 8.
Development
uv sync
uv run pytest # full suite; hash stability is the load-bearing suite
uv run python bench/benchmark.py
integrations/ holds repo-only bootstrap tooling — an importer that drafts
status: inferred contracts from a
graphify knowledge graph (see the
sales example for the walkthrough), and a
GitHub spec-kit extension
(integrations/speckit-hashloom/)
that wires the cache-and-gate loop into /speckit.implement — draft seam
contracts per feature going in, verify --radius as the definition of done
coming out. Tooling, not surface: nothing in it adds an MCP tool or CLI
command.
Kept deliberately small: 5 MCP tools, 5 CLI commands, contracts as plain YAML. Everything not in this README is an issue.
License
Apache 2.0
Hashloom MCP questions
How do I add Hashloom MCP to Claude Code?
Run claude mcp add hashloom -- uvx hashloom in your terminal. Add --scope user to make it available in every project.
How do I add Hashloom MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Hashloom MCP provide?
It exposes 5 tools, including get_contract, put_contract, get_dependents, verify, status.
How does Hashloom reduce context usage for AI agents?
It provides tiny context packets containing only the contract, dependency signatures, and callers, rather than requiring the agent to re-read entire files.
What is the benefit of the verification caching?
It avoids re-running tests if the contract, implementation, and dependency hashes have not changed, serving results from a cache instead.
How does Hashloom handle changes to software dependencies?
It calculates the exact set of invalidated dependents transitively by hash, providing a mechanical blast radius.
Can I use Hashloom with languages other than Python?
Yes, the system uses file extensions to pick language adapters for different implementations.