0.30.2 The control layer for AI-assisted development
Your AI agents say the work is done. Majordomus makes them prove it.
Majordomus keeps AI coding agents honest. It remembers what every session learned, keeps parallel agents out of each other's way, and accepts a task as finished only when your own checks pass. It works beside the agent you already use, and it never calls a model.
Open source. One command to install. No account, no sign-up. Watch it refuse unfinished work →
- Works beside the tools your team already uses
- Any tool that reads AGENTS.mdbbClaude CodeCodexGemini CLIA worker with no convention of its own
the product · this project's own delivery
This project's own plan and releases, read from its records at the commit this site was built from.
Delivery the history proves, inferred at 0fab562
Issues of the plan, by the status their records declare
Changes the release record of v0.30.1 carries, 2026-10-19
- fixed
- 18
- performance
- 1
- documentation
- 1
- housekeeping
- 1
Open the product → A snapshot, read once at this site's commit. dd4c0a8
01the problem
Agents are fast. Trust is slow.
AI agents can write code all day. The hard part is knowing what they changed, what they forgot, and whether any of it actually works.
- Context Agents forget. What one session learned dies with its conversation, and the next one starts over.
- Coordination Agents collide. Parallel workers edit the same paths, or build the same thing twice, without knowing about each other.
- Completion Done is cheap. A worker can report success before the repository's own checks hold.
Majordomus fixes all three in the one place every agent already works: your repository.
Built for the people who answer for the result
- Solo builder
- AI-native development team
- Engineering lead
- Platform and developer productivity team
- Open-source maintainer
- Agency or consultancy
- Enterprise engineering
- Research and experimental engineering
Recognise a specific moment? See the failures it answers
- re-explained the same context to a brand-new session
- found two agents fixing the same bug in two branches
- watched the strongest model, at maximum effort, rename a variable
- accepted "done" because the model said so, and paid for it the next morning
- opened CLAUDE.md and AGENTS.md and found two different rulebooks for one repository
- watched a session undo last week's decision, for the reason it was made
- found a task "in progress" that nobody had touched for three weeks
- asked what the workers did last night and had only transcripts to grep
- found the rule for that directory in a README no session ever loaded
- read three roadmaps for one project and believed none of them
All 38, by who you are and by what part of operations they fall under →
02how it works
From first prompt to a checked finish
Every task follows the same short path, whoever or whatever does the work. Your repository answers at each step, so nothing depends on an agent remembering to behave.
- 1 start begin a scoped task under a profile See it run →
- 2 context what the next worker needs to know now, within budget See it run →
- 3 checkpoint record compact progress inside the active task See it run →
- 4 check is the current task consistent with policy, scope, state? See it run →
- 5 handover write an append-only continuation record (body on stdin) See it run →
- 6 finish evaluate the finish contract; refuse if unmet See it run →
No prompt tricks and no leap of faith. If a check fails the task is not finished, and the record says why.
03what you get
Everything AI-assisted work needs, in one layer
The things every team ends up building by hand, ready on day one. Open any of them to see what it does and the evidence behind it.
-
1 · 4 features
Context
Every worker starts from what the repository already knows: the context that applies to its path, the handover the last session left, and the decisions already made.answers
Agents forget. What one session learned dies with its conversation, and the next one starts over.- claims guaranteed with a named test
- 29 of 32
- executable use cases
- 17
- rules it rests on
- 19
-
2 · 6 features
Coordination
Every worker declares the paths it will touch, sees who else is working and where, and hears about a collision before it is committed.answers
Agents collide. Parallel workers edit the same paths, or build the same thing twice, without knowing about each other.- claims guaranteed with a named test
- 40 of 41
- executable use cases
- 6
- rules it rests on
- 13
-
3 · 3 features
Governance
The rules are written once, in the repository, projected into every tool's instructions, and a blocking rule stops the command instead of advising it.answers
Rules drift. Each tool keeps its own instruction file, and a rule nobody wired into enforcement is only a suggestion.- claims guaranteed with a named test
- 25 of 29
- executable use cases
- 8
- rules it rests on
- 17
-
4 · 5 features
Evidence
A claim names the test that settles it, a recorded run is judged against the commit it ran at, and a claim with no recorded run says so.answers
Claims outrun proof. The documentation says one thing, the runtime does another, and nobody can show which is true.- claims guaranteed with a named test
- 30 of 34
- executable use cases
- 4
- rules it rests on
- 13
-
5 · 3 features
Completion
Done is a contract the repository evaluates line by line. Work is not accepted while any line fails, and a refusal stays on the record.answers
Done is cheap. A worker can report success before the repository's own checks hold.- claims guaranteed with a named test
- 16 of 16
- executable use cases
- 8
- rules it rests on
- 12
-
6 · 7 features
Surfaces
One declaration in the repository becomes the command line, the HTTP API, MCP, the UI, the Cockpit, the documentation and this site, and a projection that disagrees with it fails the build.answers
Interfaces disagree. The command line, the API, the docs and the website each keep a copy, and the copies drift.- claims guaranteed with a named test
- 35 of 35
- executable use cases
- 10
- rules it rests on
- 15
The product, by domain → All 28 features → Every feature against every interface →
04works your way
One source of truth, wherever you work
Managers follow delivery in a browser. Agents ask through their own tools. Engineers stay in the terminal. Everyone gets the same answer, because every view is generated from the same records.
-
UI
For whoever follows the delivery: health, releases, the roadmap, open work, evidence and rules, in one place.
On your own repository it is live: start the local server and it answers at
/ui -
Cockpit
For whoever wants the detail: every rule, record and check behind a figure, with its source.
On your own repository it is live: start the local server and it answers at
/cockpit -
Command line
For whoever does the work, person or agent: start a task, check it, hand it over, finish it.
-
HTTP API
For your own tools and dashboards: the same answers, over HTTP.
-
MCP
For coding agents: the same answers, as tools an agent can call.
-
Documentation
For everyone: the guides, the reference and the decisions behind them.
- capabilities in the registry
- 2645
- MCP tools
- 196
- HTTP routes
- 201
- objects of the layer
- 2439
Every feature against every interface → The registry every interface is generated from →
Bring your own AI. Keep your own rules.
Majordomus never invokes a model; it decides what a worker is told, what it may touch, and whether its claim of being done can be believed.
For engineers: one declaration reaches every interface
- declared as
- brief.session
- command line
- majordomus brief
- MCP tool
- majordomus_brief
05the proof
Watch it say no.
An agent wanders outside its task, says it is done, and is refused. It cleans up and is refused again, because your own test still fails. Only when every check passes is the work accepted. This is a recording of the real tool, not a demo script.
- worker The worker makes the change it was asked for, and also edits a note under docs, which the task never claimed.
- refused check names the file outside the claimed scope and exits non-zero. It is a failure, not a warning.
- refused The worker reports the task finished. finish evaluates the contract instead of believing it, and refuses.
- worker The stray edit is taken back.
- refused Scope is clean now, but the repository's own test still fails. finish runs it and refuses again.
- worker The worker does what the handover said was left.
- accepted Every line of the contract passes, so the outcome is recorded, with the verification that proved it.
recorded run · the worker says it is done
The worker reports the task finished. finish evaluates the contract instead of believing it, and refuses.
$ majordomus finish --outcome completed --verify-command 'sh test/parse.sh'
- pass blockers
- fail note
- fail scope
- pass state
- fail verification
finish: refused, 3 unmet
It is accepted only when every line passes: finish: t-<id> completed
Any tool can tell an agent what to do. Majordomus decides whether what it did counts, and it keeps the record either way.
The whole challenge, and how to run it yourself → The contract every refusal is evaluated against →
Every other refusal on record (12)
- $ majordomus context resolve .ai/repo/zones exit 10 Refuse a directory of the layer that documents nothing →
- $ majordomus context validate exit 10 Refuse a directory of the layer that documents nothing →
- $ majordomus context --budget-lines 30 exit 10 Read only the context that fits the budget, and know what was dropped →
- $ majordomus check exit 10 Hand work over with a question still open, and keep it blocking →
- $ majordomus check exit 10 Catch an agent that says it is done when it is not →
- $ majordomus check exit 12 Resume in the right worktree, never against somebody else’s task →
- $ majordomus finish --outcome completed --verify-command 'test -d .ai' exit 10 Decide whether finished work is actually finished →
- $ majordomus finish --outcome completed --verify-command 'test -d .ai' exit 10 Hand work over with a question still open, and keep it blocking →
- $ majordomus finish --outcome completed --verify-command 'sh test/parse.sh' exit 10 Catch an agent that says it is done when it is not →
- $ majordomus finish --outcome completed --verify-command 'sh test/parse.sh' exit 10 Catch an agent that says it is done when it is not →
- $ majordomus finish --outcome completed --note done exit 10 Prove what a task owed before calling it done →
- $ majordomus finish --outcome completed --note done exit 10 Say what reached the remote and what did not →
06evidence, not testimonials
No logos. No testimonials. Evidence.
Every figure here is computed from the repository, never typed. Each promise names the test meant to prove it, the ones a recorded run supports are counted apart from the ones only declared, and what is planned or rejected is shown in the open.
Two numbers, kept apart on purpose. Declared is a promise written down together with the test meant to prove it. Supported means that test ran against this exact revision and the run was recorded. A promise without a recorded run is counted as a promise, and as nothing more.
- confirm what you installed
- majordomus --version
The intent model, claim by claim
9 guaranteed2 planned
The intent model, claim by claim
9 guaranteed2 planned
Each claim the intent model makes is listed below under the status docs/CLAIMS.yaml declares for it, and each opens on the test that settles it. A claim promoted from planned to guaranteed moves between the lists with no edit to this page, and anything the design asks for that no claim names is a sentence in the conditional, not a capability.
guaranteed
- An intent's stage is derived from the milestones that realise it and each criterion from the evidence ledger, and it is satisfied only while every criterion has a current passing run
- An intent whose criterion names evidence that resolves to nothing is refused by name
- Once work exists under an intent, a criterion no issue serves, an issue under its milestones that serves nothing and a link to a criterion that does not exist are each refused by name
- A gap that leaves a criterion unanswered is refused, and an issue serving an intent that started without a critique or while a blocking finding is open fails intent validation
- The work realising an intent is joined across sessions, providers and handovers, and an intent whose milestones are all closed while a criterion's evidence fails is refused naming that criterion
- Asked before work on an issue, `intent preflight` names the intents the issue serves with the governance that applies, or refuses naming the cause
- The Cockpit shows every intent with its derived stage at /cockpit/intents, and one intent's criteria, evidence, serving issues and realising work at /cockpit/intents/<id>
- A task that names the issue or the intent it serves is briefed with what that intent asks of the work, and a handover tells the next worker when the intent moved
- Where the policy requires binding, starting an issue or a task that serves an intent with no critique, or with a blocking finding open, is refused when it is started rather than reported afterwards
The milestones, in the order their graph derives → The model stage by stage →
Every claim, with the test that settles it → Every rule, with its validator → What it does not do →
07get started
Running on your repository in minutes
One command installs it and one sets up your repository. It adds a single tracked directory, readable without the tool, and nothing else.
install · one command
Install majordomus in one command
No git, no Rust, no Node, no root. One archive for your machine, its digest verified before anything is unpacked, into $HOME/.local/bin.
curl -fsSL https://majordomus.dev/install.sh | sh2 · in the repository you want supervised
majordomus initWrites .ai/ — the policy, the profiles, the rules, the prompts, the workflows — and nothing else.
3 · point your agents at it
majordomus updateGenerates CLAUDE.md, AGENTS.md and the other bootstraps from the policy; every worker reads the same contract. Platforms, pinning a version, the security model →
Confirm what was installed: majordomus --version
Platforms, pinning a version, the security model Every feature Read the guarantees How this page is derived