Start here.
C10:OS is a CLI-first, text-default operating system for autonomous agents. It gives every project its own numbered room, makes every action a repeatable recipe, and records the reason behind every change. You drive it from a shell and from Claude — the system figures out the path, the recipe, and the function. This page is the shortest route from "what is this?" to "I shipped something."
The 60-second model
Four things hold the whole system together. Learn these and everything else is detail.
The spine
~/.C10 — with the master CLI, the registry, and the config. F10N4 is its keeper: no gender, no ego, just the thing that keeps the lights on.Halls
.62, .58, …). Dot-prefixed means underground and sandboxed. Each has its own justfile and reason for being.The WHY chain
why.jsonl tracks why. Append-only and immutable — every mutation carries a --why, and the chain reads back as a story.Two turntables
Get going in five steps
Land in the spine
cd ~/.C10 and type c10. The system answers with its status — services up, halls registered, your current flow state. The first thing you should ever type.
Read the room
c10 status for the briefing, c10 why for the last decisions, c10 flow to see if you're in session. You're never guessing at state — the spine tells you.
Bring an idea
Capture it as a bot job: c10 bj register "your idea". It gets classified, linked to related work, and filed — with a WHY entry. The F1X board in the Hub is the shared work queue.
Build it into a hall
Non-trivial work gets a visual plan first, then a hall. The pipeline scaffolds a new numbered room with its own justfile and .c10/. In Claude Code, /c10:start "describe the app" kicks it off.
Verify, then ship
Playwright gates verify the build before it counts. Then c10 deploy <target> --why "..." ships it. When a room crosses the threshold, the graduation ceremony drops the dot and it becomes a service.
Leave it better
Noticed something but didn't fix it? Drop a crumb. Spent C01N or earned karma? It's logged. Every loop end leaves the next person — agent or human — a cleaner room.
How it works under the covers
// the build loop
Software in C10:OS moves through one repeatable loop. Ideas enter as captures; a visual plan is drawn before any code; a pipeline scaffolds the hall; gates verify it; a stamp graduates it.
The same loop runs whether a human or an agent is driving — and several agent sessions can edit the tree at once. The discipline is what keeps that concurrency from turning into chaos.
// the path
Cascading config
.c10/ overrides its parent; everything links up to the spine at _JU135_/_admin_/config/. Local where it can be, central where it must be.G4LL3RY hosts the web
8100 serves every hall's UI — so the CLI stays independent and nothing fights over ports.The WHY chain
c10 why narrative.Graduation
etc/.Two surfaces, one system
// the fish CLI — data
c10 … in the shell gives you the facts. c10 bj list prints a table. c10 config get reads a value. Fast, scriptable, text by default — add --json when a machine needs to read it.
If you just want raw data, this is the surface.
// the /c10 commands — judgment
/c10:* inside Claude Code reads the same registries and runs the same calls, then adds a layer: it interprets, prioritizes, cross-references, and proposes the next action.
c10 bj list prints the table; /c10:bj notices three entries share a room, flags one as stale, files your idea linked to its siblings, and appends the WHY — in one step. If you want it thought about, use the slash command.
From diagram to deployed
Work climbs one ladder, bottom to top. A picture becomes a command, a command speaks JSON on demand, anything you do twice becomes a recipe — and from there it composes into anything. The same rungs carry an agent or a human.
A harness that improves itself
New verbs are cheap: drop a just recipe or a .md slash command and it's live the next session — no registration step. The system also keeps its own house: c10:doc regenerates a room's CLAUDE.md from its actual structure, diagrams re-render on a cadence, and crumbs, the bj0* registry, and the WHY chain feed every loop back into the next. The factory that builds the halls was built the same way.
A full testing backend
Verification is a gate, not an afterthought. Every hall ships its own suite — Vitest unit, integration, and e2e — and Playwright gates must pass before a build can graduate. A hermetic fleet harness (just fleet-e2e) walks the whole lifecycle — create → stamp → publish → pull → data-survival → rollback — in an isolated sandbox, so a release proves itself end-to-end before it ever touches a node.
Deployment handling, built in
c10 build --profile <p> packages the spine; c10 deploy <target> --why "..." ships it. Halls run as containers on the fleet (Docker · OrbStack) behind the G4LL3RY presenter and a Cloudflare tunnel. Fleet updates are pull-based through signed Gitea releases — staged, verified, receipted, and rollbackable. A bad config fails its fish -n check and auto-rolls-back; releases land as canary first, then promote to live.
Your first session
Add --why "..." to anything that mutates. Add --json to anything you want to pipe. Those two flags are 90% of fluency.