Orbit / how it works / for review
Orbit is a self-hosted control layer for AI coding agents. This page explains how the pieces fit together, and the one piece that's missing.
The problem
Every session starts from zero. Nothing an agent learns survives it.
An agent works out why a migration deadlocks on Tuesday. Thursday — same project, maybe a different agent — that reasoning is gone. It gets re-derived, or the same dead end gets walked again.
Why it persists: three memory stores that can't see each other — Claude Code's, Codex's, and Orbit's — two of them vendor-private. And the usual fix, a team wiki, dies of neglect.
The fix in one line: capture what every agent does through hooks that already exist, compile it once into shared project knowledge, and hand it back at the start of every session. The maintenance that kills human wikis is exactly the work a model does for free.
Graph 1
Five moving parts. Four exist today; the fifth is what's being proposed.
Human
One operator, several machines. Mostly on a phone, via Telegram.
Personal agent
Always-on assistant reachable on Telegram. Runs a PM profile per project that triages, proposes work, and asks Orbit to dispatch it.
Control layer
Mission control and system of record. Watches every session, ranks what needs attention, dispatches work, holds the state.
Workers
Claude Code and Codex CLI. Do the actual work, each in an isolated git worktree.
Reading surface
Markdown notes — the human-readable layer where Sam reads plans, tasks and knowledge.
Proposed
The shared, agent-readable memory every project is missing. Everything below is about building this.
Graph 2
One task, start to finish. Each step is done by a different player.
01
Sam messages Hermes on Telegram — "get the deploy blocker fixed".
Sam → Hermes02
That project's PM agent checks state, picks the task, and asks Orbit to dispatch it.
Hermes PM → Orbit03
Orbit starts a coding agent in its own worktree, so parallel runs never collide.
Orbit → Claude / Codex04
As it works, hooks stream what happened back to Orbit — plans, tasks, progress, blockers.
Coding agent → Orbit05
Orbit turns that raw evidence into project knowledge, and writes the human view into Obsidian.
Orbit → knowledge + vault06
Sam gets progress and approval requests on Telegram. The next session opens already knowing all of this.
Orbit → Sam, and → next agentstep 06 feeds step 01 — the loop closes, and each pass starts better informed than the last
Graph 3
The proposal itself. One rule shapes it: agents write evidence, one compiler writes knowledge. Everything below the compiler can be deleted and rebuilt.
captured by global hooks — nothing is ever written into your repositories
compiled by one writer, on a budget — small edits, or none at all
published as versioned knowledge — every page says how complete it is
projected out — every copy below is disposable and rebuildable
Status
The substrate is in daily use and covered by 645 tests. The knowledge layer is entirely unbuilt.
| Piece | State |
|---|---|
| Hooks capturing every Claude session (~7,856 events so far) | running |
| Event log with dedup and secret quarantine | running |
| Dispatch to Claude and Codex, with worktree isolation and phone approvals | running |
| Obsidian vault, search, nightly maintenance pass | running |
| Per-project Hermes PM agents | running |
| Same capture for Codex as for Claude | to build |
| Versioned project knowledge + the compiler | to build |
| Session-start briefing for every agent | to build |
| Completeness contract — pages that admit what they're missing | to build |
Two rules that shape everything
| Work projects are untouchable | Every project is tagged personal or work. Nothing is ever written inside a work repository — not a file, not a config line. So the knowledge has to live outside the repo. |
| Agents work in isolation | Dispatched runs happen in separate git worktrees. Anything written inside the repo only reaches the main branch if that branch gets merged — and abandoned branches are kept, not deleted. So knowledge must leave by a route that doesn't depend on merging. |
If you're reviewing this
Detail
This page is deliberately high level. The full architecture — content-class conflict policy, the authority model, the completeness fields, identity resolution, the 7-phase rollout, and the four corrections a prior review forced — sits in the decision register and the plan document.
| Question | Short answer |
|---|---|
| Who can publish knowledge? | Four capabilities: view · contribute evidence · publish (curator) · set policy (admin). Contributors never publish. |
| What if two agents write the same thing? | Mostly impossible by design — evidence is create-only, published pages have exactly one writer, caches are one-way. Only drafts need conflict handling. |
| How does a page prove it's current? | It carries the snapshot it reflects, how far each source was read, how many events are unprocessed or quarantined, and a plain verdict: complete, degraded, or unknown. |
| Who decides how much to trust a claim? | Orbit does, never the agent making it. An agent's claim is always recorded as "claimed"; only a human or verified system can promote it. |
| Does this touch my repo's config files? | No. Instruction files stay human-owned; context arrives through global session hooks instead. |