The session does not grade its own work.
A completion claim needs evidence per item and passes one read-only review in a fresh context. Any workspace change during the review invalidates the evidence.
A LOCAL COMPANION FOR CLAUDE CODE AND CODEX CLI
Keep your
AI work
in orbit.
A CLI session forgets its goal when its context is compacted, grades its own work and ends when its process ends. Orbit holds what the session cannot: your goal and every correction, evidence, one independent review and a durable ledger.
Open source · Apache-2.0 · macOS and Linux
FIG. 01 / A TASK IN ORBIT
SELECT A SIGNAL TO FOLLOW
THE CLI DOES THE WORK. ORBIT KEEPS IT ON COURSE.SCROLL TO FOLLOW
01 / WHY ORBIT DOES SO LITTLE
Fewer constraints.
Better work.
Claude Code and Codex do their best work with the fewest constraints. Every extra rule, planning call or per-turn manager costs tokens and attention. So Orbit does not wrap your terminal, does not plan for the model, does not manage it turn by turn, and calls no model while nothing is wrong.
- No terminal wrapper
- No planner call
- No per-turn manager
- No model call while nothing is wrong
It holds only what a session cannot hold for itself:
- 01
The goal survives.
Your request and every correction are fixed and re-presented after compaction and in the next session.
GOAL → BRIEF - 02
Evidence per item.
Each completion item carries evidence recorded from commands actually run.
COMMAND → EVIDENCE - 03
One independent review.
The completion claim gets one read-only review in a fresh context. The session does not grade its own work.
CLAIM → REVIEW - 04
A durable ledger.
It survives the process. Handoffs and measurements are generated from it, never written by hand.
EVENTS → LEDGER - 05
A lean context.
At a measured point, the work continues in a fresh session rebuilt from the ledger.
LEDGER → FRESH SESSION
Everything else is left to the native CLI. Orbit judges itself by one thing: the result.
02 / ONE TASK, START TO VERIFIED
Compacted.
Still on course.
Four illustrative terminal scenes from one attached session: the brief after compaction, evidence, the independent review and the verdict. Example output, not a live agent.
/compact
Context compacted. Orbit hands back the brief.
GOALFix add(): it subtracts instead of adding.
CORRECTION 1Keep the public signature.
DONE (rev 1)D1 · add(2,3) returns 5 · 0
D2 · subtraction is no longer used · 0
NEXTcosmos-orbit evidence T-042 D1 --command '[…]'
Every stop is managed.
Orbit reads from the ledger why the session stopped, with no model call, and gives the one next step that fits. Items without evidence go back by name; unmet items come back with the reviewer’s fix list.
Self-reports are claims, not proof.
Evidence the executor recorded about itself reaches the reviewer as claims to check. A claim without evidence is returned unmet.
These checks reduce unsupported completion claims. They are not mathematical proof that software is correct.
03 / A LEAN CONTEXT
Hand off
at a measured point.
A long session re-reads its whole context on every turn, and long contexts dilute attention. Orbit measures each session from the host’s own transcript. At the handoff point, the work continues in a fresh session rebuilt from the ledger: the brief, the checkpoint and only the files it needs.
CONTEXTSCHEMATIC, NOT DATA
Default handoff point. A setting, in three scopes.
Cost-equivalent tokens saved at 350k when 113 of the author’s own Claude Code sessions were replayed (2026-11-04).
Fewer handoffs than at 200k: 150–177 instead of 444–1,075.
In cmux or tmux, with context auto, Orbit types it itself. Your next request runs in the fresh session. Nothing to retype.
A hook cannot clear its own session, so a handoff ends one of three ways:
- AYou type
/clearor/new - BThe host compacts the session
- COrbit types
/clear(opt-in, Claude Code in cmux or tmux)
Replays of the author’s own sessions, not a promise for yours. An earlier replay of 99 sessions with a handoff at 200k saved 31–51%. Cost-equivalent: input ×1, cache write ×1.25, cache read ×0.1. Measure your own sessions before you change the point. python3 scripts/measure_context_growth.py --days 14
04 / BETWEEN SESSIONS
An idle session
wakes up by itself.
Codex to Claude Code, Claude Code to Claude Code. A session waiting at its input line runs no hook, so a message used to sit unread until you typed “check it” yourself. Now the sender calls one command, and Orbit looks at the receiving screen and acts on what it sees.
RECEIVING PANE · CMUX / TMUX
The fixed line is never recorded as your prompt and never changes the goal. The session is told it carries another agent’s words, not your instruction.
| The receiving screen | What Orbit does |
|---|---|
| Working | Waits until the turn ends, then wakes it |
| The input line is empty | Types one fixed line and Enter |
| You are typing there | Never erases anything. One notification, then it waits |
| A dialog or a shell | Types nothing, notifies and keeps looking |
| Not in cmux or tmux | Notifies only |
Your own typing is never erased.
The fixed line is never recorded as your prompt and never changes the goal. The session is told it carries another agent’s words, not your instruction.
One waker per pane · at least 20 seconds between typed wakes · at most 20 per pane per hour · after 30 minutes the waker gives up and the message stays in the mailbox.
05 / SELF-EVOLUTION, IN TWO LAYERS
It improves itself.
Your habits stay yours.
A built-in evolution agent watches for things that went wrong in Orbit itself. What your use teaches stays on your machine as data. Only general defect fixes can reach the code.
Learned here. Kept here.
How you phrase a question versus a request, and where your sessions should hand off, is learned from your own store and applied automatically. None of it is ever written into the code.
YOUR STORE · ~/.local/share/local-harness
- How you phrase a question versus a request
- Where your sessions should hand off
cosmos-orbit evolve --reset-learnedDefects of Orbit, never preferences.
A maintainer turns it on. Anonymised signals become candidates, and a fix is written test-first in a fresh worktree. It must pass four gates:
- 1Checks
Every check passes, and the new one fails on the base commit.
- 2No personal traces
No home path, name, host, address, id or four words in a row from your prompts.
- 3No vocabulary in code
Added lines are plain ASCII. Words belong to the personal layer.
- 4Generality
A fresh, read-only reviewer judges it useful to any user.
A change that fails any gate is never pushed.
06 / OBSERVE THE SAME WORK
What Orbit did is
visible, not assumed.
The engine room and cosmos-orbit watch read the same task store: the completion checklist, evidence, fixed-check exit codes, reviews, the stop reason, the handoff mode and the panes a message can wake.
INTERACTIVE PREVIEWRotate it, zoom in, inspect an engine. Twelve synthetic sessions run in your browser: no installation, account or AI calls. An interactive preview of the real UI, not a recording.
Open the interactive engine room$ cosmos-orbit watch --once
T-042 verified D1 ✓ D2 ✓ review: met
handoff: tell · 350k wake: 2 panes
Observation does not start model work. The dashboard binds to 127.0.0.1 and is a local, single-user interface.
07 / PUT IT IN ORBIT
Your next task
stays on course.
Open source. Apache-2.0.
macOS or Linux, Python 3.9+, Git and an installed, authenticated Claude Code or Codex CLI.
01
Install once
Clone, install and add the hooks. They stay inert until something is switched on.
TERMINAL / PYTHON 3.9+
git clone https://github.com/honeyground-org/cosmos-orbit.git
cd cosmos-orbit && ./install.sh
cosmos-orbit hooks install02
Switch it on, at any scope
Every project, one project, or one terminal. The terminal wins, then the project, then global.
TERMINAL
cosmos-orbit on --globalevery projectcosmos-orbit onthis projectORBIT=on claudethis terminal only
03
Work as you already do
Use your normal command. Nothing else changes, and Orbit never commits, pushes or deploys task changes.
TERMINAL
claudeClaude CodecodexCodex CLI