npx github:frdyx/maddu init

The problem

You've handed real work to AI agents. They claim lanes, request approvals, ship slices, hand off to each other — often several at once. And the moment a session ends, the control goes with it.

• Who's actually in charge? Two agents editing the same thing, and nothing holding the line between them.
• Did that approval get honored — or just clicked past? You can't tell from a chat log you can't grep, on a machine you're not on.
• Can I trust what happened while I was away? Scattered across SQLite files, vendor dashboards, and agent memory you can't inspect — with no way to prove it wasn't quietly rewritten.

Agents are getting more autonomous. The thing that governs and coordinates them shouldn't be the least durable part of your stack.

Tracing tools observe runs. Memory layers help agents remember. Máddu governs how agents collaborate.

The category

Local-first cooperative agent governance. Not a control plane, not a gateway, not a proxy — a governance layer the agent itself calls; one NDJSON file you can tail; nothing leaves your machine. Local-first is operational, not marketing: delete .maddu/ and Máddu is gone — and git clone brings the whole governance history with it. Enterprise platforms govern which agents run in your org; Máddu governs how they work once they're in your repo. The canonical definition — and why every nearby name already means something else — lives in docs/45-category.md.

Frameworks build the agent. Durable-execution engines keep it running. Observability watches the model. Memory layers feed the agent's future. Orchestrators spawn the swarm. Máddu is the neutral record your repo owns that lets you verify what any of them actually did — and govern what leaves.

The idea

One append-only log on disk is the single source of truth. Everything else is derived from it — and thrown away on conflict.

That's the whole bet. When every approval, session boundary, lane claim, and slice of work is one line in one file, the hard questions get easy:

tail -n 1 .maddu/events/000000000001.ndjson

{"v":1,"type":"SLICE_STOP","actor":"ses_20260518081409_b7f312","data":{"summary":"wired the bridge to my repo"}}

Every state question reduces to tail, grep, or git log on a file you already own. No SQLite to crack open. No dashboard between you and the truth. The log replays deterministically on any machine, so the answer is the same everywhere — forever.

The discipline loop is the product

What Máddu gives every install, from day one, is the always-on core: register a session, claim a lane, run a slice, stop it with a structured summary, let the gates check it — each one line on the spine. That disciplined substrate is the value; it's what makes the history trustworthy. Multi-agent orchestration (coordinator, loop, pipeline, team) is a powerful opt-in layer on top — reach for it when a job fans out across lanes, skip it when it doesn't. Most work just needs the loop, and that's by design. (See the charter for the core-vs-orchestration split.)

And with maddu hooks install, the loop stops being advisory: a PreToolUse hook blocks a mutating edit when the ritual is stale — no session, no lane, no governing goal/plan, an overdue slice-stop, or uncommitted work piling up — so in-harness drift off the record is blocked rather than silent. It's tier-scaled by governance (strict blocks, standard warns then blocks, relaxed only nudges), fails open (any error allows the edit; it never crashes a tool), and never gates the remedy (maddu slice-stop, git commit…), so the fix is always one command away. Claude Code-specific; every runtime still gets the record. See Session hooks.

How it works

Three moving parts, and nothing else:

Everything under .maddu/state/ is a projection: rebuildable from the spine, discarded on conflict. The spine always wins. There is no maddu spine repair by design — corruption surfaces by name, with file-and-line precision, and you decide what to do about it.

The record is a contract, not just a log

Append-only and hash-chained means a naive after-the-fact edit can't pass unnoticed — it breaks the forward prev_hash link and spine verify FAILs — and since v1.117.0 every event is also stamped with a workspace identity derived from the spine's own genesis line, riding inside the hash preimage, so a chain-valid line lifted from another workspace's spine can't re-chain here either (the chain is unkeyed, so a determined actor who recomputes the whole chain, truncates the tail, or edits only the last event is out of scope — the OS's job; see the threat model). Máddu goes one step further: every event conforms to a published, versioned contract — 193 typed event types emitted as a real JSON Schema (docs/event-schema.json, draft 2020-12), fingerprinted so it can't silently drift (a shape change fails CI without a matching semver bump; the version rides on the record itself as x-contractVersion). So your governance record isn't only tamper-detecting — it's independently checkable: someone who trusts neither you nor Máddu can validate the spine against its own published contract with off-the-shelf tooling.

docs/event-schema.json     the published contract (JSON Schema, draft 2020-12 · x-contractVersion 1.17.0)
                           → validate any spine event against it with ajv, check-jsonschema, or any validator

What the contract attests is precise — and worth stating precisely: a third party can validate that every event is well-formed against the published schema without trusting you or Máddu, and maddu spine verify checks that the stored chain is internally consistent (unkeyed — a full recompute or tail truncation is out of its scope). Neither attests that the work the record describes was good — that's what gates, replay, and your own review are for. (And handing the record over is lower-risk by design: payloads get best-effort write-time redaction — see SECURITY.md for its limits.)

Get running in 60 seconds

$ npx github:frdyx/maddu init
Máddu v1.118.0 installed.

Next step: open this repo in Claude Code or Codex CLI and type:

  /maddu-help                # discover the slash-command surface
  /maddu-suggest <task>      # "what should I run for X?"
  /maddu-autopilot <task>    # end-to-end task pipeline

That's it. The operator surface is slash commands — no flags to memorize, no CLI verbs to recall. Type a slash command (or just natural language — "ship the login form", "status", "tokens") and the agent classifies your intent, dispatches the right action, and tells you which one it chose.

For any non-trivial feature or fix, the agent reaches for a pipeline by default — maddu pipeline run ship-a-feature "<goal>" (plus fix-a-bug and plan-and-delegate) — walking one canonical flow: orient → plan → coordinate → slice → test → review → land → account.

Power users & CI: the verbose CLI is always there — it's what the slash commands dispatch under the hood. ./maddu/run start, ./maddu/run register, ./maddu/run slice-stop "…". Full walkthrough → docs/01-getting-started.md.

The operator surface

Inside Claude Code or Codex CLI, you drive everything from one line:

…and a dozen more (/maddu-skill, /maddu-insights, /maddu-debt, /maddu-architecture, /maddu-handoff, /maddu-advise …). Full reference → 22-slash-commands.md + natural-language routing.

And for the person who can't read the code — the one on the hook for what the agent did — there's a read-only Operator Plane on top of the same record: maddu status --line (a one-line on-goal/drift segment, wireable into the status line), maddu orient --digest ("while you were away"), an oversight readout of what a skill was fed vs withheld and the plain-language why (maddu spine oversight), a per-project cockpit, a decision ledger whose every row ties to the tamper chain, and a cross-workspace portfolio wall that surfaces which repos need a human. All read-only projections — nothing new is written to make them. See Oversight and the Operator Plane.

Eight ways people run it

Same substrate, eight shapes of work. Every workflow below is real commands against the same append-only record — pick the one that looks like your week.

🔍 1. Verify the agent instead of trusting it

For anyone who's been burned by "done ✅, tests pass" that wasn't. The 2026 lesson of agentic coding is that generation stopped being the bottleneck — verification is. An agent's chat summary is the actor grading its own work. Máddu makes the record the witness instead.

maddu hooks install            # sessions auto-register on the spine (Claude Code; fails open)
# … agent works, then:
maddu slice-stop "…"           # deliverables + gates + learnings → one line on the spine
maddu learn scan               # hedged "should work now" claims vs OBSERVED proof
maddu orient                   # goal progress verified by real commands, not vibes

Completion-claim language in slice-stops is checked against the record — confident verification claims are matched to recorded proof, hedged claims are counted, and a recent spike trips a warn-tier gate (machinery-gated, so pre-existing work isn't policed). A model checking a model is a second opinion; this is a check against the record — a signal, not proof.

🚀 2. The independent app builder

For the solo dev shipping a real product with Claude Code or Codex. You don't want ceremony — you want to say "ship the login form", walk away, and trust what you find when you come back. The discipline loop runs underneath without you thinking about it.

npx github:frdyx/maddu init && maddu hooks install    # once
/maddu-autopilot ship the login form                  # end-to-end pipeline
# overnight run? every iteration lands as a slice-stop with gate results
maddu orient                                          # morning: the timeline, not a 100k-line transcript

Overnight autonomous runs become reviewable: pre-compaction checkpoints mark what survived context loss, the focus instrument tags each turn toward/lateral/away from your declared goal, and the morning is a ten-minute skim of slice-stops with gate badges — not an archaeology dig.

👥 3. A team sharing one repo

For teams whose agents (and humans) keep stepping on each other. The record syncs through the git remote you already have — no server, no daemon, no new credentials, no vendor between you and your own history.

maddu spine sync init          # opt in; this checkout gets its own partition
maddu spine sync               # commit own segments → pull → validate → audited push
maddu status                   # contentions surface BY NAME — never silent double-writes

Each checkout appends only to its own partition, so git never line-merges the record. Identity rides your remote's own access control. Concurrent claims on the same lane don't corrupt anything — the merged read surfaces them as contentions with the superseded sessions named.

🐝 4. A swarm of parallel agents

For operators running 3–20 coding agents at once — with Agent Teams, Conductor, Claude Squad, or your own scripts. Git worktrees became the consensus isolation primitive; Máddu is the durable record underneath whichever spawner you use, not a competing one.

maddu lane claim payments --worktree    # isolated checkout, bound to the claim
# … each agent works its own lane, appends to the SAME primary spine …
maddu lane release payments --worktree merged   # explicit disposition — verified, not asserted

One agent per lane is a hard rule, --worktree gives each its own checkout on its own branch, and merged disposition actually checks git merge-base — Máddu never runs your merge, it verifies you did. The dashboards vanish when the run ends; the record survives it.

✅ 5. CI for agents

For repos that want agent work held to the same bar as human PRs. One CI step reads the record and exits nonzero when the evidence is missing — deterministic, no LLM, no network.

- run: npx github:frdyx/maddu ci     # gates ran? deliverables real? secrets clean? claims backed?

You pin which gates are required (maddu ci pin) — pinning fixes which gate IDs are required, so an upgrade can't silently add or drop required gates; a pinned gate's implementation can still change (framework upgrade, or a same-ID operator override shadowing the builtin). Same exit code drives GitHub Actions, GitLab, or a fully-offline git pre-push hook.

🎓 6. Governed experience data — for training pipelines and audits

For teams fine-tuning small models on their own agent trajectories, and for anyone who owes an auditor an account. The 2026 training stack standardized the format for agent-trajectory data — but the leading protocol's own paper leaves redaction, secrets, and governance explicitly out of scope. That's the part Máddu does.

maddu experience                      # the spine as trajectories of typed steps + outcome signals
maddu evolve plan                     # evidence-gated recommendations — or an honest "change nothing"
maddu experience export --format atdp --out exp.atdp.json   # the governed boundary
maddu export --otel                   # or: OpenTelemetry logs into the stack you already run

The export is deterministic (byte-identical re-runs — that is the audit trail), refuses outright on any secret-shaped value with no flag to override, and ships trainingEligibility: false until you — not a regex — judge the data. It's the honest on-ramp into trajectory-curation pipelines, not a dataset grab. And if regulation is on your radar: record-keeping regimes like the EU AI Act (Art. 12) push toward automatic, reconstructable logs of AI-assisted decisions — an append-only record you own and retain locally is a building block for that traceability, not a compliance product.

🏭 7. The SLM factory — governing model training

For teams fine-tuning domain-specific small models. TRL/PEFT train, vLLM serves, SWE-bench and BFCL evaluate — excellent tools at every step, and none of them is the neutral record of what happened between the steps. Máddu is: datasets, training runs, evals, and promotions land as hash-pinned manifests on the spine, and a checkpoint's stage is derived from the record — a manifest can't claim its way toward production.

maddu model dataset snapshot models/tickets-v3.json  # license, split, provenance — recorded + pinned
maddu model train complete models/run-42.json        # config of record: base hash, seed, commit
maddu model eval record models/eval-7.json           # + critical regressions: acknowledged or blocking
maddu model promote models/promote.json              # the approval ride — no auto-decide near production
maddu model gates install                            # 12 ML-lifecycle gates in .maddu/gates/ — yours, ci-pinnable

Every promotion above candidate waits for an explicit per-request decision — standing approval policies are deliberately inert near production. Rollback is strictly downward and re-promotion goes back through the full ride; the spine verifier holds the whole ladder tamper-detecting on replay. And the honesty line is structural: Máddu records what your tools declared and pins the bytes of record — it never trains, serves, evaluates, or decides that a model is good. Full guide: 51-slm-governance.md.

🕰️ 8. Proof for someone who doesn't trust you

For the reviewer, the auditor, the client — or future-you — who won't take your machine's word for it. Everything above verifies the agent on your machine, under your authority. This shape escalates the evidence past that boundary: each rung of the assurance ladder names exactly what backs it, and no rung is granted by local state.

maddu spine verify --replay <sha>   # clean checkout of that exact commit re-runs the DECLARED verification
maddu spine anchor                  # stamp a receipt of the record into Bitcoin (OpenTimestamps)
maddu spine anchor --assess         # operator consume ceremony — records the assurance level, honestly labeled

actor-reported is the agent's own receipt, preserved. replayed re-runs the repo's declared checks in a clean clone of the exact commit and appends its own strict receipt. anchored commits a receipt (and chain head) to Bitcoin via the stock OpenTimestamps client — evidence that exists outside the actor's authority, which no after-the-fact rewrite can back-date. The consume ceremony can only refuse, never vouch: the positive evidence is the operator's own ots verify, and ASSURANCE_ASSESSED is labeled a non-authoritative ledger note by every consumer. Combined with the workspace-stamped, hash-chained record and the published event contract, a skeptic can check what happened without trusting you, your agent, or Máddu itself.

What it does for you

The spine is the foundation. This is what you actually get standing on top of it — every item is a real command, and every step it takes lands as an event on the spine.

🎛️ Zero learning curve

There's nothing to memorize. Inside Claude Code or Codex, type a slash command — or just say what you want:

ship the login form        → runs the ship-a-feature pipeline
status                     → /maddu-status
tokens this week           → /maddu-cost
what should I run for X?    → /maddu-suggest

The agent reads your intent from MADDU.md, dispatches the matching command, and tells you which one it chose — so you learn the surface by using it, not by studying it. The verbose CLI stays first-class underneath for scripts and CI; the slash layer is just the part humans touch.

🧭 Architecture-drift detection

Most "architecture" lives in a diagram that's wrong by the next sprint. Máddu makes it executable. You declare the allowed module boundaries once in .maddu/config/architecture.json; then maddu architecture builds the real import graph from your code and diffs it against the contract:

• Drift, by name — forbidden cross-area edges, dependency cycles, and undeclared areas, each reported with file precision.
• A diagram you can trust — it renders the actual graph as mermaid, generated from the code, not hand-drawn.
• A CI gate with a ratchet — the architecture-drift gate fails on a failOn ladder (none / new / any), and a structural-mass baseline enforces "monoliths may only shrink." Drift can't sneak in between reviews.

✅ Governance as a merge requirement

maddu ci runs every deterministic gate headlessly — no LLM, no network — and exits nonzero only on gates your repo has pinned as required (maddu ci pin), so framework upgrades can add gates without ever turning your pipeline red until you opt in. One branch-protection rule later, agent work doesn't merge unless the governance record is green:

- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with: { node-version: 20 }
- run: npx github:frdyx/maddu ci

No GitHub? No problem — the same exit code drives a fully-offline git pre-push hook (exec maddu ci) or any other CI system. Failed required gates surface as GitHub annotations plus a one-table job summary when Actions is detected. Full contract in docs/46-ci.md.

Why Máddu

Six design choices — and the thing each one lets you do that you couldn't before.

The 8+1 hard rules

Nine invariants. maddu doctor verifies them on every install and every upgrade; maddu audit traces each one to the gate that enforces it. A repo that violates any of them is not a Máddu repo.

These rules govern how Máddu itself is built — its own orchestration code — never the product you build with it. The app you ship can use any database, SDK, or backend it needs. See the scope banner in docs/hard-rules.md.

Full text and rationale → docs/hard-rules.md.

Documentation

Design tokens, typography, motion → docs/DESIGN-SYSTEM.md. Full version history → CHANGELOG.md.

Why the name

Máddu (North Sámi) means root, origin, ancestry — the spirit-source from which an instance descends. Pronounced MOD-doo. The name isn't decoration: every action, claim, slice, and approval in this framework descends from a recorded ancestor on an append-only event spine. The word captures that property more precisely than any English equivalent we tried.

License

Apache-2.0. See LICENSE.

Homepage: maddu.frdyx.com · Source & issues: github.com/frdyx/maddu.

Contributing: Máddu is post-1.0 but evolves fast — expect tag-boundary changes, and read docs/charter.md for the invariants that won't.