Coltrane

Teach Claude to play jazz.

The power of language models is in their improvisational ability, sometimes called hallucinations. The power of jazz is how the math creates the space for exploring new territory safely. Music theory — translated through a good player, a good band, and a good standard that says when to walk and when to leap.

In honor and reverence for John Coltrane, whose courage to leap, and to leap, and to leap has taught so many to find the bravery to do the same themselves.

In his footsteps,

Eugene — Tokyo, June 2026

If you're a human, this README is for you. If you're a Claude reading this, stop here and open CLAUDE.md — that file is written for you; this one is written for the people you play with.

Run it

Node 26 or newer is required. A skill's network grant is enforced by --allow-net, which arrived in Node 25 (already end-of-life); on Node 24 and older a skill can reach the network with no gate at all. So coltrane refuses to run a skill on anything older than 26 — coltrane, coltrane-server and every skill execution refuse at start, naming the reason; there is no degraded mode. Imported as a library (@eir-labs/coltrane/tool_surface, ./genome_store), the package installs and loads on Node 24.

nvm install 26          # or any Node 26+
npm install -g @eir-labs/coltrane

Three verbs and a JSON file:

coltrane validate                       # load the genome; non-zero exit on any error
coltrane dispatch <standard> --input @in.json --depth skim
coltrane trace <output-id>              # walk a result back to its root signals

And a fourth for the band pattern: coltrane work claims one queued gig from an organization's store — atomically, under a lease, authorized by the chair contract the agent is seated on — runs it under the claimed gig's own id, and drains the sealed results back. A queue, a worker, and an audit chain, with no coordination structure beyond the gig table itself.

coltrane validate is the one worth wiring into CI. It exits non-zero on any definition the loader cannot resolve, which turns a genome change from something a person has to remember to check into a job that fails in seconds without spending a token.

As an MCP server instead. Point .mcp.json at the installed package and the mcp__coltrane__* tools appear in any MCP client:

{ "mcpServers": { "coltrane": {
    "command": "node",
    "args": ["./node_modules/@eir-labs/coltrane/dist/src/server_entry.js"],
    "env": { "COLTRANE_GENOME": "${PWD}" } } } }

Or clone this repo and open Claude Code in it — it ships its own .mcp.json, and on a fresh clone Claude offers to calibrate the instrument to you before any work starts.

What this is

Coltrane is an instrument and codex to improve Claude in place — and it is, at once, the instrument, the player, and the band.

Right now there is no real way to manage a fleet of agents consistently. You define them in JSON, but nothing enforces what they are, what they're allowed to touch, or how they change. It's fuzzy, and fuzzy doesn't scale. Coltrane is the substrate that makes a band of agents coordinated, bounded, and accountable — so complex work gets done reliably, instead of impressively once.

The bet underneath it: the reason jazz works is that music theory is well-defined, and every player follows it when it counts. Music theory is math. The most efficient way to build systems of small intelligences is to treat them like players in a band — and to invest in coordination over raw intelligence. A well-orchestrated band of modest players beats one virtuoso trying to do everything: lower cost, higher reliability, more interesting territory explored.

The four North Stars (first release)

Traceability — what ran, what changed, how it ran, why this result. Every gig seals a genome_hash + run_fingerprint into an append-only ledger, and every output knows its parents. You can walk any result back to the raw input and the wiring that produced it — which standard ran, which agents filled which chairs, and which outputs fed which.

genome_hash is a structural hash: it covers the standard's phase graph and each agent's slug, primitives, input_types, output_types, and domain. It deliberately does not cover an agent's identity, method, constraints, behavioral_primitives, allowed_tools, model tier, or skill_slugs. Two genomes that differ only in those fields produce the same genome_hash — and therefore the same run_fingerprint when their outputs coincide. So the chain answers "was the wiring the same?", not "was the prompt the same?". Authoring-time content_hash/effective_hash (sealed by agent_define and friends) do cover the full definition bytes; those are the hashes to compare when you need behavioral identity. Resume and reuse fold a third hash, producers_sha, over the whole agent definition plus each skill's verified code_hash — so an edit under a stable slug cannot silently splice two genomes together across a resume.

Reproducibility — can I run it reliably? Is it correct? Is it true? The same genome replays byte-for-byte. The fingerprint distinguishes an honest replay from a tamper, so "it worked" becomes a checkable claim instead of a vibe.

Blast radius — when an agent is compromised, how wrong can it go? You can't stop a model from being prompt-injected. You can use mathematics to bound the scope of what it's able to do when it is — and prove that bound in tests. Optimize for the blast radius, not the fantasy of perfect prevention. That bound isn't aspirational: an agent's tool grants resolve to real providers or the dispatch fails closed, and a browser runs only inside a deny-by-default origin cage.

Cost optimization — spend inference on what matters. Don't burn tokens on plumbing, or on work you've already done once. The system learns where to stop paying for inference, and we keep adding encoding tricks that lower the effective cost of the work. Every run now records what it actually spent — per model — so "spend on what matters" is something you measure, not just hope. This is a pillar, not a footnote — it compounds, and it's where much of the near-, mid-, and long-term roadmap lives.

How to think in standards

A jazz standard is the computationally-reduced description of something wildly improvisational: a chord progression with a few colorings, on a single page, that any player is expected to pick up, pivot into the right key, and play well enough. You don't hand a musician every note — you hand them the shape and trust their training to fill it.

Coltrane standards work the same way. The leverage is up top, at definition time:

• Model the domain first. Before doing the work, pause and dispatch a gig to define the type space of the domain — its shapes and the relationships between them. This formal step up front buys enormous solidity downstream. Let Coltrane learn a little about the domain, then run research / double-diamond standards to explore it in more dimensions than you'd think to on your own. (The fun part: push a book through a pipeline built for a codebase and watch what falls out — typed data run through consistent processes finds connections nobody asked for.)
• Orientation is everything. Players aren't freely swappable; the orientation of an agent is the single biggest predictor of whether the band coheres. Claude can play almost any instrument — you just have to point it at the right method before the work starts.
• The score is built at runtime. Prompts don't live in hand-edited .md files. The work is encoded into the genome and decoded at runtime for whatever model is playing (Claude today; the pattern is model-agnostic). An agent doesn't wake up and figure out its life — it opens its eyes to a seat, an instrument, a score, and a downbeat. Then it plays.

The quartet — named seats, bound by contract

The default genome ships three named agents — john, bill, and miles, their lineage rooted formally in the players the engine is named for — and one example institution (institutions/quartet.json) that binds them: chairs carry the dispatch grant ({"grant": "dispatch", "standards": [...]}) naming which standards the seat may run; assignments seat the agents; forebear records and lineage edges carry real citations. Authority sits on the office, not the player: swap who holds the chair and the contract stands. Two default standards — software-change-v1 and product-design-v1 — give the quartet real work, and tests/default_genome_quartet.test.ts holds a grant naming a missing standard to be a dead name that fails at authoring time. The pattern is the product: an organization is what you'd call a project, its chairs carry the roles, and any player fit for the seat can sit in it.

Since the first release

• A command line. The package shipped only an MCP server, so the engine was reachable from an interactive client and nowhere else — not CI, not cron, not a container. coltrane fixes that.
• Checkpoint and resume. A run that stops partway no longer discards the phases that finished. --resume continues from the last sealed phase, and refuses rather than silently running cold if the genome, the producers, the payload or the model moved since.
• Improvement as a measurement. improvement_report buckets a producer's outputs by version and by model tier, reporting cost and quality together — so "did that change help?" and "does the cheaper model still clear the bar?" are questions with answers. Unmeasured quantities report null, never 0.
• The skill loop. Browse, inspect, execute against fixtures, evolve, promote. A candidate runs against the current fixtures in a throwaway copy and lands only on a clean pass, so a skill cannot regress through that door — and a code skill must pass its own fixtures, deterministically, to become active.
• One surface, any host. The full tool registry is a mountable module (createToolSurface): the stdio server, a hosted HTTP deployment with OAuth, and a test harness all mount the same 49 tools. A genome can live in files or in an organization's instance store (GenomeStore), loaded per-caller; the repo's genome is the base repertoire every deployment starts from.
• The worker. coltrane work — claim, run, drain. Claims are atomic and leased (a worker that dies leaves an expiring lease, not a stuck row); authorization derives from the chair contract; a failed run records failure, with its reason, in the same chain a success records completion.
• Discoverability parity. Every genome class you can author over the wire you can list over the wire (standard_browse, agent_browse joined type_browse, skill_browse) — an invariant with a test, learned the honest way: the first hosted session could compose a standard but not discover one.

What's next

• Memory. Cut the context a thread needs at cold start. A shared memory layer the runtime can fold into what it already constructs up front. 10x reduction in token usage is the target.
• Test-driven pipelines. Plug your Claude into Coltrane and invoke standards that enforce TDD by construction — the test is the contract for entering the pipeline, written before the code.
• Open conclusions + attestation. When an agent reaches a value it can't confirm from deterministic signal — a hallucination risk, or a human-in-the-loop call — it marks the conclusion open, goes and finds a real source, brings it back, and logs the attribution into the ledger. Chain of custody for an idea, traced back to a person or a verified source.

Contributing

This repo is meant to be improved by the people running it — including by the agents you run inside it. Working with Coltrane and working on Coltrane are the same motion. Open a pull request; the maintainer's agents review it, and we decide together what to integrate.

Cross-language reproducibility

Three published hashes identify the reference vector. Any implementation that reproduces them byte-for-byte interoperates; an independent Python reference already does.

e88dff82403e35c07bce390b88ecb5995ebada86db83242d2ac0a8ff558d37da   meta.json
d778a51deac04f56d1fb5456b2b1498505320c64043b5f402d2dfe27baf21ea4   skill.md
25e74fe11444b604f4715e984a1f101dcf7cdd135035696175acf508d54f0fe3   definition hash

License

Apache-2.0. Fork it. Ship it.