orbit

<p align="center"> <a href="https://orbit-cli.com"> <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/assets/orbit-lockup-on-dark.svg" /> <img src="docs/assets/orbit-lockup-on-light.svg" alt="Orbit" width="340" /> </picture> </a> </p> <h3 align="center">Agents write. Orbit delivers.</h3> <p align="center"> <a href="https://github.com/constellation-works/orbit/releases"><img src="https://img.shields.io/github/v/release/constellation-works/orbit" alt="Release" /></a> <a href="https://www.npmjs.com/package/@orbit-tools/cli"><img src="https://img.shields.io/npm/v/@orbit-tools/cli" alt="npm" /></a> <a href="LICENSE.md"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License: MIT" /></a> <a href="https://orbit-cli.com"><img src="https://img.shields.io/badge/docs-orbit--cli.com-informational" alt="Docs" /></a> </p> <p align="center"> <img src="docs/assets/orbit-demo.gif" alt="Animated tour of the real Orbit dashboard on a live workspace: proposed tasks waiting for your approval, an auto-drain running tasks in parallel while overlapping work waits on file locks, a task's durable record, the run list, a pull-request pipeline run stepping from isolated worktree through implement, commit, review gate, and push to pr_open, the audit log of every tool call, and a scoreboard comparing Codex, Claude, Grok, and Gemini." width="880" /> </p>

Orbit is a local-first runtime for coding agents. You keep using Claude Code, Codex, Cursor, Copilot, or any of the other supported CLIs. Orbit gives them a durable task queue, isolated sandboxed worktrees, file-level locks for parallel runs, a gated pipeline that ends in a pull request, and an audit log of every step.

Why: agents are fast enough that planning, review, and traceability are the first things to go. Six months later nobody can say why a line was written. Orbit makes those disciplines cheap and keeps you out of the clerical work. The agent files the task, Orbit runs it, and every commit carries a task ID you can trace back to the prompt, the plan, and the review.

• Single binary, no cloud. State lives in ~/.orbit and .orbit/. Nothing phones home.
• Bring your own agents. Orbit drives the provider CLIs you already have authenticated, and never asks for API keys.
• MIT licensed. No paid tier, no hosted offering.

---

How it works

$ orbit init                                 # one-time, per machine
$ cd my-repo && orbit workspace init --mcp   # per repo; wires Orbit into your agent CLIs
$ orbit web serve                            # open the Orbit dashboard in your browser

You:    The fsProfile lookup is undocumented. Get that fixed.
Agent:  orbit.task.add       → ORB-1042 · proposed
        Filed with acceptance criteria. Approve it and ship?
You:    Yes.
Agent:  orbit.task.update    → ORB-1042 · backlog
        orbit.workflow.ship  → worktree isolated · file scope locked · plan → execute → review
        Pull request opened. ORB-1042 is in review. The diff and the merge are yours.

$ orbit task update ORB-1042 --approve       # after you merge: review → done

_{Illustrative session. The tool names are real, and the IDs are placeholders.}

For more than one task, hand your agent a spec and ask it to orchestrate. The bundled orbit-orchestrate skill splits the spec into tasks, queues them once you approve, runs them in parallel with orbit run auto, and diagnoses any run that fails.

1. Nothing starts without you. New tasks land in proposed, and only your approval moves them to backlog.
2. Every run ends at a pull request. Orbit never merges on its own. Merging the PR and completing the task are separate decisions, unless you explicitly pass --complete.
3. Everything is on the record. orbit task show ORB-1042 reconstructs the prompt, plan, execution trace, and review thread, even months later.

---

Quick start

You need: macOS or Linux (x64 or arm64; on Windows, run Orbit inside WSL2, as there is no native Windows build: see the Windows WSL2 guide), Node 18+, at least one authenticated agent CLI, plus gh authenticated if you want pull requests.

npm install -g @orbit-tools/cli
orbit init    # asks for a machine name and a task-ID prefix, links Orbit's skills into your agents, and on Linux prepares the sandbox

Then let your agent set up the repo. Open your agent in the repository and ask it to "set up Orbit for this repo". The bundled orbit-setup skill registers the repo, connects your agent over MCP, and runs orbit doctor, asking only for what it can't infer, such as the branch pull requests should target. Start a fresh agent session when it finishes so the Orbit tools load, then ask for something: it files the task, asks for approval, ships it, and reports the PR. Watch it all with orbit web serve.

<details> <summary>Set up the repo by hand</summary>

cd <repo> && orbit workspace init --mcp    # add --ship-mode local to skip PRs
orbit doctor
orbit web serve

Review and commit the checkout files listed by workspace init before the first ship. Local delivery requires a clean base checkout; the list includes MCP client files.

orbit doctor reports missing CLIs for crews selected by the default, system, or complexity routing and warns when no Orbit MCP client is registered for this workspace. It checks CLI presence and registration files only; provider sign-in and MCP connectivity are not checked. Use orbit doctor providers to inspect all executor definitions, including providers not selected by workflow routing. On Linux, see sandbox readiness and distro coverage.

</details>

| To… | Run | |---|---| | Inspect a task or run | orbit task show <ID> · orbit run show <RUN_ID> | | Open the dashboard | orbit web serve (remote: orbit web connect <host>) | | Pick the default crew (provider and model) | orbit config set workflow.default_crew <crew> | | Upgrade | npm install -g @orbit-tools/cli@latest (orbit update --check shows what's new) |

<details> <summary><strong>The same loop without an agent</strong></summary>

Every MCP tool has a CLI twin.

TASK_ID=$(orbit task add --title "..." --description "..." \
  --acceptance-criteria "..." --complexity medium --workspace .)
orbit task update "$TASK_ID" --approve   # proposed → backlog
orbit run ship "$TASK_ID"                # async; prints a run ID
orbit run show <RUN_ID>                  # progress and outcome
orbit task update "$TASK_ID" --approve   # after merging the PR: review → done

</details>

---

Features

Plan and govern

• Durable tasks with intent. Tasks carry acceptance criteria, a file scope, dependencies, and typed relations. They move through proposed → backlog → in-progress → review → done, and that state survives sessions and branches.
• Structured audit log. Every tool call, provider exchange, and state transition is recorded as an append-only, queryable event tagged with the agent and model that produced it (orbit audit).
• Friction ledger. When the work was harder than it should have been, whether from a confusing error, a missing flag, or an undocumented convention, the agent records it with orbit friction add instead of quietly working around it. A task that resolves the friction closes it on completion.
• Local search. orbit search runs fast lexical search (SQLite FTS5) over tasks and frictions. It needs no model download.

Execute safely in parallel

• Isolated, sandboxed runs. Each run gets its own git worktree and runs its agent CLI under sandbox-exec on macOS or Bubblewrap on Linux. On Linux, worker runs are also memory-bounded in a cgroup.
• Conflict-aware scheduling. Runs reserve their task's files as locks before starting, so overlapping work waits in line instead of producing merge conflicts later.
• Gated pipeline. Each run goes plan → execute → review, with repair budgets and failure recovery. Dependencies gate admission, so you declare the order once and the queue enforces it.
• Nine agent CLIs, routed by crews. Claude Code, Codex, Cursor, Copilot, Grok, Gemini, Antigravity, OpenCode, and Pi. Crews pin a provider, model, and effort level. Complexity-tiered, weighted crew pools spread the work across them.

Run unattended

• Bounded drains. orbit run auto --for 4h --concurrency 8 ships the backlog until the time window closes. orbit run readiness previews what would run without starting anything. Or ask your agent to run one: the orbit-orchestrate skill prepares the backlog, starts the drain, and works through failed runs.
• Opt-in completion. --complete merges PRs once GitHub allows it and closes tasks after the merge is verified. Nothing else turns this on.
• Continuous review. The shipped code-review, qa-sweep, and security-review auto-tasks read everything that landed since their last run, verify findings against live code, and file confirmed ones as tasks with file:line evidence.
• Recurring work as data. Scheduled task templates live in .orbit/auto_tasks/*.yaml, and one machine scheduler (orbit clock) runs routines and auto-tasks.
• Multi-machine. A distributed drain spreads a backlog across machines through durable claims. A federated MCP server puts local and SSH-remote workspaces under one namespace.

Observe and extend

• Dashboard (orbit web serve). Shows the task backlog, live audit feed, per-agent scoreboard, jobs, frictions, and effective config, with inline editing.
• Plugins (orbit plugin). A plugin can add its own tools, jobs, routines, auto-tasks, skills, and CLI commands. Plugins run sandboxed under explicit permission grants, and orbit plugin scaffold generates a starter.
• Agent skills. Three skills ship with Orbit: orbit (everyday task work), orbit-orchestrate (backlog and dispatch), and orbit-setup (machine and repo configuration). orbit init links them into your agents.

You can adopt these one at a time. The task layer and audit log work from day one. Parallel drains, auto-tasks, and plugins switch on when you want them.

---

Agent plugins

To give a single agent Orbit's MCP tools and skills without installing the CLI on PATH, add the plugin. It launches the pinned npm CLI. The dashboard and cross-agent workspace setup still need the CLI install.

# Claude Code
/plugin marketplace add constellation-works/orbit
/plugin install orbit

# Codex CLI
codex plugin marketplace add constellation-works/orbit --ref agent-main
codex plugin add orbit@orbit

# Cursor (local plugin from a checkout)
mkdir -p ~/.cursor/plugins/local && ln -sfn "$(pwd)/plugin" ~/.cursor/plugins/local/orbit

Want to be walked through setup? Ask your agent to "set up Orbit for this repo", and the bundled orbit-setup skill takes it from there.

Claude Code desktop

In Claude Code the plugin also brings the Orbit mod: a band above the prompt with the workspace's running, blocked, and review counts, and an Orbit pane with a task board, a ship view that preflights and tracks orbit run ship, and an orbital map. Open them with /orbit-board, /orbit-ship, and /orbit-map. When the checkout is a replica, set the plugin's ownerHost option to the owner's SSH host. See plugin/hooks/mod.

Codex desktop

You need Node.js 18+ (including npx) and the Codex CLI on PATH.

1. Register the Orbit marketplace from a terminal:

   codex plugin marketplace add constellation-works/orbit --ref agent-main
   

2. Restart the desktop app. Open the Plugins Directory, choose the Orbit marketplace, and install Orbit.

3. Start a new chat in your repo and ask: "set up Orbit for this repo".

See the official marketplace setup guide.

---

MCP and authority

orbit workspace init --mcp registers orbit mcp serve --operator with your agent CLIs. That operator session is the only one that can dispatch workflows, resume runs, or run commands. Agents launched by Orbit get an agent-only surface. Authority is enforced when a tool is called, not by hiding tools, so every session sees the same tools/list. Use orbit mcp init alone for an agent-only registration, or orbit mcp init --federated to put several machines under one namespace (details).

Where state lives

| Path | Holds | |---|---| | ~/.orbit/ | Machine state: task bundles, orbit.db (audit, runs, routines, frictions), workspace registry, shipped resources, skills, config.toml | | <repo>/.orbit/ | Workspace state: identity, local config overrides, auto-tasks, routines, worktrees, and logs. Gitignored, and safe to delete for a clean slate. |

Backups, stuck runs, database recovery, and upgrades are covered in the runbooks.

---

Learn more

• orbit-cli.com: guides, concepts, and the full CLI and config reference
• docs/CONFIG.md: crews, pools, base branch, sandbox
• docs/POSITIONING.md: what Orbit is for, and what it deliberately isn't
• ARCHITECTURE.md and design docs
• CHANGELOG.md: Orbit is pre-1.0, and breaking changes ship in minor releases

Contributing

Pull requests are welcome, from typo fixes to new executors. Small fixes can go straight to a PR, and bigger changes start with an issue. See CONTRIBUTING.md to get set up.

License

MIT