For a year my unofficial job title was message bus. I ran sub-agents from my terminal, copied outputs, pasted them into the next prompt, and hoped nothing drifted along the way. The agent was never the bottleneck; the organization around it didn't exist. This is the build log of Nirvana-OS, the engine I wrote to fix that: what I designed, what I traded away, and what is still rough in beta. I built it and maintain it, and I'll flag every limitation I know about.
The problem: artisanal orchestration
- Pasted prompts as the transport layer between sub-agents
- Zero reproducibility: the same pipeline never runs the same way twice
- Token burn visible only on the invoice, never per step
- The five-hour reset arriving mid-pipeline with nothing resumable
Design bet: prose in, receipt out
- The only input is an order in natural language; no DSL, no dashboard
- The only trustworthy output is an append-only audit trail
- Three guarantees enforced by design: Traceable, Tested, Contracted
Three registries: companies, squads, mind-clones
- Companies: org charts written in natural language (a folder of roles, not a process)
- Squads: portable, file-defined workflows; shareable and versionable
- Mind-clones: 5-layer persona files (philosophies, mental models, heuristics, frameworks, methodologies) so a role carries method, not a one-liner
Compiling a squad into a DAG with quality gates
- Squad file format and how it compiles to nodes and edges
- Gate types: schema validation and acceptance checklists
- Fail-loud behavior: a failed gate blocks downstream and redispatches upstream with failure notes
The audit trail: append-only or it didn't happen
- Why the log is never rewritten, even on failure
- Anatomy of a receipt: dispatches, gate results, artifact paths, per-step token cost
- Real receipt excerpt from a full run (pasted as text, not a screenshot)
Runtime-agnostic by adapter
- The engine drives Claude Code, Codex, or Gemini-CLI instead of shipping a model loop
- What an adapter has to implement
- Honest mileage report: Claude Code is the best-tested runtime by far
Licensing: source-available, said with a straight face
- SUL v1.0: free to read, run, and modify for your own use; specific commercial uses need a license
- Not OSI-approved, and the README says so; why I chose it over MIT (a paid content pack funds the engine)
- Lesson: stating the license category up front beats being corrected in the comments
What's still broken in beta
- v0.1.57, 21 releases, 41 stars: early, and priced into every claim here
- The receipt reports cost after the run; it doesn't predict it
- Conservative concurrency cap, because sub-agent fan-out multiplies spend
Closing
The bet underneath all of this is small and testable: an agent you already pay for can run an organization defined entirely as files, if every step is gated and every run leaves a receipt. Beta v0.1.57 is where that bet stands today: 21 releases in, free to use, source published under SUL v1.0, best tested on Claude Code. If you install it and a receipt ever fails to explain a run, that's a bug. File it, and I'll fix it in the open: https://github.com/gutomec/nirvana-os-engine
Top comments (0)