Orbit — The engineering framework for your AI coding agents

The Orbit dashboard (orbit web serve) — task backlog, live audit log, per-agent scoreboard.

Orbit takes review off the critical path, so throughput and rigor stop trading against each other. A durable task for every change, structured audit of every tool call and provider exchange, conflict-aware parallel dispatch, and continuous review sweeps that file what they find straight back into the backlog — local-first.

You drive Claude Code, Codex, Grok Build, or Gemini CLI against real code, often in parallel. Agents make it easy to skip the disciplines that keep code maintainable, and six months later nobody can reconstruct why an agent wrote a given line. Orbit makes those disciplines cheap: tasks before edits, every tool call in a structured audit log, parallel runs sandboxed into worktrees with file-level locks, and your own design docs retrievable by the agents doing the work.

Conventional practice buys safety with blocking gates, which caps how many agents you can run at once. Orbit merges on a quick direction check, then scheduled code-review, qa-sweep, and security-review passes read the merged window and file every confirmed finding back into the backlog as an ordinary task. Every commit carries its task ID, so the history stays reconstructable.

Features

• Durable, intent-tracked task layer. Lifecycle (proposed → backlog → in-progress → review → done) survives sessions and branches; every commit carries the task_id, so orbit task show reconstructs prompt, plan, execution trace, and review threads months later. → docs/design/task-artifacts/
• Structured audit log. Every tool call, provider exchange, and task transition is a queryable, append-only event with agent identity attached. → docs/design/auditability/
• Conflict-aware parallel execution. orbit run ship gives each run its own git worktree and reserves task context_files as locks before fanning out, rejecting overlapping reservations up front instead of producing merge conflicts later. → docs/design/activity-job/
• Continuous review, not blocking review. Shipped code-review, qa-sweep, and security-review auto-tasks read the window since their last cursor, verify findings against live code, and file confirmed ones as tasks with file:line evidence. A clean window is a successful no-op. → docs/design/auto-tasks/
• Sandboxed-by-default execution. Dispatched agent CLIs run under sandbox-exec on macOS and Bubblewrap on Linux; the Linux boundary enforces writes only, leaving host reads and network open. Unsupported platforms keep the in-process filesystem guards. → docs/design/policy-sandbox/
• A searchable docs corpus — your conventions, not Orbit's. Register the markdown you already write with orbit docs add; agents retrieve it by concept via orbit search --kind doc, with --hybrid adding embedding recall. → docs/design/orbit-docs/
• A friction ledger for what made the work harder than it should have been. A confusing error, a missing flag, an undocumented convention — Orbit's own tooling being one case among many — the agent files it (orbit friction add) instead of silently working around it. A task carrying a resolves relation closes its friction on reaching done.
• Dependency-ordered execution. Tasks carry dependencies and typed relations; the pipeline gates admission on them, so declare the order once and let the queue enforce it.
• Recurring work as data. orbit auto-task defines .orbit/auto_tasks/*.yaml templates with a cron or interval schedule and a dedupe policy; a seeded scheduler mints tasks from the due ones, and orbit auto-task mint <name> mints one on demand.

Everything is incremental: the task layer and audit log work on day one; the docs corpus, friction ledger, auto-tasks, and parallel dispatch switch on as you adopt them.

Quick Start

Prerequisites: at least one supported agent CLI (Claude Code, Codex, Cursor, or Gemini CLI), authenticated. orbit run ship in its default --mode pr needs gh authenticated; otherwise use --mode local. On Linux, complete the Linux sandbox runbook after orbit init.

curl -sSf https://raw.githubusercontent.com/constellation-works/orbit/main/install.sh | sh
# or: brew install constellation-works/tap/orbit

orbit init                                 # global state (~/.orbit)
cd <repo> && orbit workspace init --mcp    # workspace state + operator-authorized MCP integration

TASK_ID=$(orbit task add --title "..." --description "..." \
  --acceptance-criteria "..." --complexity medium --workspace .)
orbit task update "$TASK_ID" --status backlog   # approve into the backlog

orbit run ship                             # conflict-aware parallel flush of the backlog to PRs
orbit run show <RUN_ID>                    # step-by-step progress
orbit web serve                            # dashboard over every registered workspace
orbit web connect my-server                # ...or a remote workspace over an SSH tunnel

Or ask your agent: "create an orbit task to refactor the authentication logic in …". Full command reference: orbit --help and orbit-cli.com. Crews (which provider-model runs a task) and the base branch: docs/CONFIG.md.

Agent plugins

Use a plugin to attach Orbit's MCP tools and orbit skill to one agent without the CLI on $PATH; use the CLI install for the dashboard and cross-agent workspace setup. All three load plugin/skills/orbit and launch the npm CLI pinned to that release (npx -y @orbit-tools/cli@<version> mcp serve). Cursor's public marketplace listing is a separate human-reviewed catalog update; a git tag does not publish it.

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

# Codex CLI
codex plugin marketplace add constellation-works/orbit --ref 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

Clone and customize

Cloning gives you a framework to mold to your team's conventions; everything under .orbit/ carries over from a binary install. Paste the prompt below into your agent from inside the repo where you want Orbit.

Search

orbit search queries tasks, docs, and frictions (--kind task|doc|friction|all), lexical by default. --hybrid adds embedding ranking over tasks and indexed docs, and orbit search similar <task-id> finds cosine-neighbor tasks. The embedder is a separate companion subprocess, so semantic search costs nothing when unused.

orbit semantic install    # one-time: companion + default model (bge-small)
orbit semantic index      # backfill existing tasks; later task writes embed automatically
orbit docs index          # backfill docs for --kind doc --hybrid
orbit search "race in the scheduler when locks overlap" --hybrid --kind task

The companion is released for macOS arm64 and Linux x86_64/aarch64 (glibc >= 2.38); Intel macOS runs the CLI without semantic search. Frictions are never embedded.

Agent Skills