Orbital: a project agent that owns the context instead of the session

The unit of work moves from the session to the project

The problem Orbital is built around is stated in the README as a question: is your context actually yours?

The scenario is specific. You are three rounds into a design discussion with Claude Code when it stops with a message that you are out of usage credits. Your Codex quota is available, but Codex knows nothing about the project, not the goal, not the two decisions you just made, not the half-edited files. You would have to explain all of it again.

The README generalises it: people use several capable agents at work, for the newest model, for leftover quota, or because one tool fits a job better, and each one locks its context inside its own session. Close the session or switch tools and that context is out of reach. The result is that you become the agent's intern, copying and pasting, ferrying context and remembering where the odd files live, while the agent does the thinking.

Orbital's answer is to take the context out of the session and put it back in the local folder, changing the unit of work from the session to the project. The framing line is that every agent owns a session while Orbital owns the project, and the summary is that individual agents complete tasks while Orbital moves the whole project forward.

So the audience is a developer who already uses coding agents daily and has hit the friction of switching between them, not a team looking for a general agent framework.

Five plain files hold the context that would otherwise fragment

The design decision that makes the idea concrete is that the context is not hidden in a database or a proprietary store. Orbital maintains five things, all of them as plain files in the project folder.

State is what is true about the project now, kept in PROJECT_STATE.md. Decisions are what was decided and why, in DECISIONS.md. Lessons are what the project has learned, in LESSONS.md. Work is what is running, completed or blocked, held in queue.json. Artifacts are what the agents researched, wrote or built, which is the workspace itself plus an orbital/output/ directory.

Because they are plain files in the project, they survive the application, they can be committed, they can be reviewed, and they can be read without Orbital running at all. The README's point is that these things normally disappear or fragment between agent sessions, and that the files stay in the local project and become context for future work. On a cold start, Orbital assembles them into its own system prompt before it acts.

The repository root also carries AGENTS.md and CLAUDE.md, which is worth noting because it shows the project living alongside the per-agent convention rather than replacing it. Orbital's own project is documented in those files, which is also the clearest possible statement of the format it expects a project to keep.

Every queued task must end as Completed or Blocked

The queue is where Orbital stops being a notes system and starts being a manager, and the rule is strict. Every queued task ends Completed or Blocked, and an agent that stops without a verdict gets re-prompted, then force-blocked with a reason. The README states the intent plainly: nothing drifts away silently.

That is a real failure mode of agent work. An agent that runs out of context, hits a wall or simply stops leaves a task in an ambiguous state, and the project accumulates a set of things that are probably fine but nobody has checked. A forced verdict turns that ambiguity into a visible state, and a blocked task with a recorded reason is information rather than noise.

The work state lives in queue.json, so it is the one piece of the context set that is machine-read rather than prose written for a human. The rest are markdown files that a person could read and edit, which is a deliberate asymmetry: the decision log and the state summary are for people, the queue is for the tool.

The other half of the mechanism is what Orbital does with the result. When a task finishes, Orbital reads the result and records what matters back into the project, so the next agent inherits the outcome rather than the transcript.

Workers are briefed from the same files on every dispatch

Delegation is the part of the system where an implementation usually has to choose between a static prompt and a live one, and Orbital documents the live option.

When Orbital delegates, the worker is pointed at those same five files and told they are authoritative, and the briefing is rendered fresh on every dispatch rather than being something you paste in. That detail matters more than it first appears. A briefing assembled at session start goes stale the moment the project moves, and a worker given stale instructions will confidently act on decisions that have since been reversed.

Each worker also keeps its own memory file inside the project, so it accumulates its own experience across dispatches. There are therefore two levels of memory: the shared project files that all agents read, and a per-worker file that captures what that particular worker has learned. The first is what makes agents interchangeable, and the second is what keeps an individual worker from starting from zero each time.

The result of that arrangement is the sentence the README puts at the end of the section: the worker can change, and the project continues.

For a user, the practical difference shows up in the agent picker, which the README describes as showing how much of each agent's usage window is left, with a screenshot showing Claude Code at 67 percent of its week and Codex at 84. Switching to another agent continues the same conversation from the same project context.

It installs as a desktop app, and the manifest is where the real detail lives

Orbital is distributed as installers, with a Windows .exe and a macOS .dmg linked from the latest GitHub release, and the README states that setup takes under five minutes, requires no Python or Node, and asks you to bring your own API key. The platform badges cover Windows and macOS only, so there is no Linux build advertised.

Behind that installer sits a Python application. The pyproject.toml names the package agent-os at version 0.17.0, requires Python 3.11 or later, and depends on openai, anthropic, fastapi, uvicorn, httpx, trafilatura, keyring, python-multipart, websockets, croniter, psutil, aiofiles, watchdog and pyyaml. The source lives in agent_os/, with a web/ directory for the interface, an installer/ directory, scripts/, tests/ and docs/.

Two optional dependency groups show the feature surface. A browser group pulls in patchright, and an office group pulls in python-docx, openpyxl and python-pptx, described as pure-Python document generation and parsing with no pandoc or LibreOffice, tied to a spec for office documents and a skill hint in agent_os/agent/prompt_builder.py. A macos group adds an EventKit calendar source, and the comment notes that the calendar hub degrades gracefully when it is absent, which is why the group stays optional.

The croniter dependency, next to croniter's role in the README's mention of automations in the user guide, is what a scheduled or recurring task feature would sit on.

The project also has a Chinese README, a Discord community, a WeChat group, and a hosted user guide at orbital.top, with the guide covering API keys, projects, switching agents, the task queue, automations and project settings.

Version caps are deliberate and the comments say why

The dependency pins in pyproject.toml are the most informative part of the manifest, because the comments explain the reasoning rather than leaving the constraints as bare numbers.

claude-agent-sdk is capped at greater than or equal to 0.2.160 and below 0.3. The comment says 0.2.x is what CI already installs, with no lock file, and that the v0.14.2 app shipped 0.2.157. The cap is there so the next minor is a deliberate upgrade, and the reason given is that SDKTransport reads SDK internals, specifically the reader TaskHandle and RateLimitInfo.raw.

mcp is held at greater than or equal to 1.2 and below 2. The comment explains that mcp 2.0.0, released on 2026-08-19, drops streamablehttp_client from mcp.client.streamable_http, and that agent_os/connectors/mcp_client.py imports it at module scope, so a fresh install could not import agent_os.connectors at all. The comment is unusually blunt that this is production code rather than just tests, that it broke CI, and that it would have shipped inside the packaged app. The instruction is to lift the cap only together with a 2.x migration of the client.

agent-client-protocol is pinned exactly at 0.11.0, with no range at all, which is the strictest constraint in the file.

Reading these comments tells you more about the project's engineering than the feature list does. A project that pins an exact version of a protocol package and explains in the manifest why an upper bound exists is a project where dependency drift is a known, managed risk. It also means your own upgrade of these libraries will conflict with the application unless you take on the migration Orbital has not done yet.

Where Orbital is the wrong tool

Several honest limits.

The first is that it adds a layer between you and your agents. If you use one agent, on one project, and never hit a limit, the five context files are extra bookkeeping. The README's own framing implies this: the problem it solves appears when you switch agents or lose a session, and if that never happens to you the value is close to zero.

The second is the GPL-3.0 licence, recorded in the licence badge and with a LICENSE file and a NOTICE file in the repository root. It applies to the application, and a team shipping the application inside a proprietary product would want to read those files. It does not reach the agents themselves, whose terms come from their own providers, and it does not reach the project files Orbital writes into your repository, which are yours.

The third is the dependency fragility described above, which lands on you if you try to run from source or to vendor anything. The fourth is platform coverage: Windows and macOS are advertised, and there is no Linux build.

And there is a genuine alternative worth weighing, which is visible in this repository's own root. AGENTS.md and CLAUDE.md are the per-agent convention: one file per agent, read by that agent, living next to the code. The difference in approach is that Orbital centralises. It keeps one project-owned set of files that any agent can be pointed at, adds a queue that enforces verdicts, and gives each worker a memory file so that a delegated task carries forward. The per-agent file approach is simpler, has no application to install, and puts the context in the hands of the agent rather than the tool, at the cost of nothing being shared between agents and nothing tracking what is running.

Editorial conclusion

Adopt Orbital if you work across several coding agents, you regularly hit a usage limit mid-task, and you want decisions, state and lessons to survive in your repository rather than in a transcript. Do not adopt it if you work on Linux, if you would rather keep your context in a single per-agent file such as AGENTS.md or CLAUDE.md, or if the GPL-3.0 licence does not fit your distribution model. Before installing, read the pyproject.toml caps, because the project deliberately holds claude-agent-sdk below 0.3, agent-client-protocol at 0.11.0 and mcp below 2.0, and note that v0.16.0 shipped on 2026-10-12 while the manifest already says 0.17.0.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. zqiren/Orbital on GitHub