Orbit needs Orbit

A model helps you define a solution: it sorts out your ideas and suggests where to cut. Once the solution is defined, it produces faster than you can follow.

This keeps happening to me across projects. The last one was a complicated feature in Orbit: it ended up in a branch I left alone, unmerged, because we reached a point where neither the model nor I knew whether the result matched what we had defined.

That is why I started working on Orbit, a cockpit for coding agents.

You run several of them at once without losing track of what each one did, and without living inside the terminal watching them one by one.

Before I ask for code

I sit down and organize the problem before asking anyone for code, person or model: what solution I want, what I am going to build it with, the tradeoffs I accept.

Then I decide what the first version is for. What stays out is usually the hardest call, because everything looks necessary when you see it all together.

A model lets you take on more than before, so now there are more things that could go in.

Then I cut that into small pieces and group them into phases, each phase with its milestone, and each milestone written as what has to be working when it ends.

I try to start every feature this way.

The guardrails

You have to tell a model how work gets done in your repository. Some of it goes into a document it reads, and some of it goes in as limits that break the build if it steps over them.

The English word for that is guardrails. Orbit has a few, these six among them:

• 300 lines per file. Going over breaks the build.
• 100 columns per line, and that number can only go down. The test holding it keeps today's count as the ceiling.
• 16 architecture tests that fail the build over design decisions. One fires if a package exports something that is not a door, another if an import shows up outside the layer map, another if go.mod adds a dependency nobody argued for.
• Six kinds of test, each with its own when: unit, property-based, fuzzing, integration against the real binary, mutation testing before the pull request, and adversarial.
• 90% coverage as a floor, with the command exiting in error when it drops.
• A linter that normalizes the shape of the text. Four different engines write Orbit's code, and without it there would be four styles living in the same repository.

All of it runs with one command:

make check

August 23 to September 13

751 commits and 143 pull requests went in, with activity on all 22 days straight. That is around 80,500 lines of production Go and another 99,300 of tests, with no third-party code copied in and nothing generated.

By week:

Each pull request there is a closed task, with its tests and its review. None of that architecture existed before. I was building it while the code came out.

That pace also owes something to the base idea being clear from the start. Every feature started with its definition and its phases, and I iterated on the rest along the way without waiting for it to be perfect.

AI moves faster than you can review

The guardrails do their job. The change reaches the pull request well formed and with its tests, so that part stops weighing on the review.

The other question is still open: whether the change does what was asked.

There were days of 18 pull requests. Before each one you spend minutes watching the console, waiting to see whether it will finish, whether it will do what you asked, or whether it understood something else.

Reviewing each one, working out what it touched and why, wears you down fast. By the fifth review of the day you are approving on the strength of the tests passing.

What Orbit is for

You hand it a task and it goes off to work. You can have several running at the same time.

• Each task runs in its own worktree, so they do not step on each other.
• When you come back, what it did is already written down: the steps it took, what it said along the way, and what got affected beyond the files it touched.
• None of them ship anything alone. They stop first and wait for you to approve.
• A supervisor reviews the work before you do, and you can ask it what it found.
• You define the steps: the same milestones from before you started, each with its model and its permissions. Orbit ships with a few ready to go.

The Spider-Man meme

I reached the conclusion that I need Orbit to keep building Orbit.

So I use it daily while I add what is missing.

The parts of Orbit

Working with a model you lose what each task cost, how long it took, and what you could learn from the earlier ones.

One post for each:

1. Getting started
2. What you can do
3. A run, end to end
4. Autopilot
5. Many tasks at once
6. Reading what it did
7. The CLI, both ways
8. The supervisor
9. What Orbit knows
10. Flows you write yourself
11. Switching provider mid-task without losing context
12. The brain, once it exists

Go have a look

Orbit is open source, Apache 2.0. It runs on macOS and Linux. It installs with one line:

curl -fsSL https://getorbit.sh/install.sh | bash

The repository is at github.com/e1i0r/orbit and the site at getorbit.sh. The numbers above come from the git history and the GitHub API, so you can pull them yourself.

The 16 architecture tests live in internal/arch. And if you want to get your hands in, CONTRIBUTING.md is short. What you send has to clear the same guardrails from above, and make check tells you before you open the pull request.