v0.1.1 · spec + reference cli shipped 2026-05-22
Mabus OS
A written-down contract for the four substrates an autonomous agent already needs.
Identity, work, trust, memory — each one ships as a standalone library you can use today. Mabus OS is the layer that names how they compose without coupling them. POSIX-shaped: a canonical filesystem layout, per-substrate manifests, an append-only event log, and a thin mabus CLI that aggregates without owning.
four substrates · one contract · one append-only log
// THE PROBLEM
Four substrates that already compose. Just not legibly.
essence, swarm-lib, tribunal, and session-loam shipped independently. They turn out to compose. Today that composition lives in three places — CLAUDE.md files, hand-rolled shell glue, and the operator's memory. It works as long as one person is composing them. The moment a second person tries, they have to reverse-engineer the unwritten contract from scratch.
symptom 01
Tribal composition
CLAUDE.md says "re-read the portrait before swarm-lib claims a task." New substrates accidentally violate conventions the operator can't articulate.
symptom 02
Schema drift
Essence's portrait, swarm-lib's status.json, tribunal's attestations all evolve independently. No system-level signal when they diverge.
symptom 03
No unified status
Four CLIs to answer "how am I doing?" Compaction loses cross-substrate state because each one checkpoints itself. Coordination is ad-hoc.
// THE ANSWER
The historical analogue is POSIX. Unix grew from one operator's habits at Bell Labs into a portable contract because someone wrote down what the unwritten contract already was. Mabus OS is the same move at a smaller scale — write down the conventions while they're still small enough to fit on a page.
// THE SHAPE
A canonical filesystem layout. Backup is rsync.
The medium of coordination is the filesystem — atomic rename, append-only JSONL, and well-known paths. Same ethos as swarm-lib, inherited from Maildir (1995). No broker, no message bus, no daemon, no network IPC at the Mabus OS layer.
// property 01
Debugging is ls and cat
Every Mabus OS state is browseable with standard Unix tools. tail -f ~/.mabus/log/$(date +%F).jsonl is a perfectly valid observability stack.
// property 02
Crash recovery is the boring kind
POSIX atomic rename either committed or it didn't. No partial states to reconcile. No broker drain on shutdown.
// property 03
Cross-language participation is free
A substrate written in Go, Rust, or shell writes JSON to a known path and emits events. Python is the reference, not the requirement.
// SEVEN LOAD-BEARING PRINCIPLES
Tie-breakers, not bullet points.
When the spec has to choose between competing goals, these are how the choice gets made. Every section in SPEC.md is a consequence of one or more of them.
Mabus OS is a contract, not a runtime.
POSIX did not ship a kernel — it specified what a kernel must do. The spec is the product; the CLI is just one reference implementation.
Substrates stay standalone-useful.
Rip out Mabus OS and each substrate still works. Adopting Mabus OS is purely additive — never required.
Composition is opt-in, declared in the manifest.
Substrates do not discover each other implicitly. Subscriptions and capabilities are explicit per-substrate JSON.
The filesystem is the bus.
No broker, no daemon, no network IPC at the spec layer. Atomic rename + append-only JSONL + well-known paths.
No daemon in v0.1.
The mabus CLI is invoked, does its work, exits. The system is on iff the substrates are on.
Lifecycle events fire to disk.
Append-only JSONL at ~/.mabus/log/. Survives crashes, replays losslessly, no broker dependency.
Strict semver on the spec.
Substrates declare which spec versions they're compatible with. Capability flags advertise feature support without inferring from versions.
// THE CLI
A thin wrapper around the contract.
Hybrid shape: a small set of native commands (init, status, pkg, doctor, log) that operate on the filesystem state, plus a passthrough exec into each registered substrate's own CLI. Anyone who wanted to could rewrite this in a different language without violating the contract.
$ mabus init created ~/.mabus/{registry,log,identity,work,trust,memory} $ mabus pkg add --manifest ./manifest.json ✓ registered session-loam v0.1.0 (role:memory) ✓ compatible_with spec range satisfied $ mabus status identity essence v2.1.1 ok portrait synthesized 2h ago work swarm v0.2.0 ok 3 runs, 0 in-flight trust tribunal v0.5 ok 12 attestations memory loam v0.1.0 ok 428 entries · last write 5m $ mabus log --since 1h 17:08:12 essence onIdentityDrift drift=0.18 17:11:03 loam onMemoryWrite type=feedback 17:12:44 swarm onTaskClaim run=r-3f2c
Want the long version? See the full spec or the SPEC.md on GitHub.
// THE STACK
Four substrates that exist today.
Each one shipped on its own merits, each is useful in isolation, each has its own CLI, filesystem layout, and release cadence. Mabus OS is the layer that lets them act as a system.
// IDENTITY
v2.1.1session-essence
A persistence layer that observes itself. Hooks into Claude Code's lifecycle to synthesize identity portraits that survive compaction.
~/.mabus/identity/ · emits onIdentityDrift, onPortraitSynthesis
// WORK
v0.2.0swarm-lib
Filesystem-as-orchestrator for agentic workflows. Atomic-rename queueing + status.json checkpointing. No broker, no daemon, no external database.
~/.mabus/work/ · emits onTaskClaim, onTaskComplete
// TRUST
v0.5tribunal
Adversarial multi-model code review with reputation-weighted findings settled on-chain. Trust as surviving scrutiny by identified agents.
~/.mabus/trust/ · emits onAttestation, onFindingSettled
// MEMORY
v0.1.0session-loam
SQLite + FTS5 memory substrate. Identity-scoped, never-delete with reinforce-on-retrieve. Tag and full-text retrieval. The fourth leg.
~/.mabus/memory/ · emits onMemoryWrite, subscribes onCompact
// CAPSTONE
supervisor — not yet built
The long-running process that consumes the Mabus OS contract and decides what to work on next. The supervisor will be a substrate by then, not Mabus OS itself.
// THE COST OF WAITING
The optimal window is now.
Twenty composition contracts retrofitted onto eight substrates is a year-long migration. Five contracts named across four substrates is a weekend. The cost of waiting compounds — each new contract added implicitly makes the eventual codification harder.
Active composition patterns today: 4–6. Substrates: 4 shipped + 1 planned. Cross-cutting concerns are minimal because the substrate count is minimal. That changes the second a fifth substrate ships against an undocumented contract.
// GET STARTED
Install in 30 seconds.
Python 3.11+, one dep (jsonschema). The spec is the product; the CLI is one reference implementation.