Provides a local-first runtime for coding agents with a durable task queue, sandboxed worktrees, and a gated delivery pipeline.
Also known as constellation-works/orbit, @orbit-tools/cli
- Stars
- 21
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.19.0
- Last commit
- Nov 15, 2026
- License
- MIT
What is Orbit MCP?
Orbit provides a local-first runtime for coding agents with a durable task queue, sandboxed worktrees, and a gated delivery pipeline.
Summary generated from the project's README
About Orbit MCP server
Orbit provides a local-first runtime designed to manage coding agents through a durable task queue and sandboxed worktrees. It is built for developers who want to maintain control over agentic workflows without relying on cloud-based services or sharing API keys. The system operates entirely on your machine, storing state in local directories and sending no telemetry. It works by adding a layer of governance around your existing authenticated agent CLIs, providing file locks to prevent overlapping work during parallel runs and a gated delivery pipeline for safer code integration.
Users can manage the entire lifecycle of an agentic task, from initial proposal and planning to execution and review. The platform includes a web dashboard accessible via orbit web serve to monitor task progress, CPU and memory forecasts, and backlog estimates. It supports macOS and Linux, while Windows users can run it through WSL2. Developers can integrate Orbit as a plugin for tools like Claude Code, Codex, or Cursor, or use the bundled orbit-orchestrate skill to split large specifications into manageable, parallelized tasks.
What you can do with it
- 1Manage agentic task lifecyclesAn AI client can propose a task with specific acceptance criteria that requires human approval before execution.
- 2Execute complex specifications in parallelA developer can use the orchestration skill to break down large requirements into multiple queued tasks that run simultaneously.
- 3Maintain an audit trail for changesThe system tracks the original prompt, the execution trace, and the review for every single workflow commit.
Written from the project's README. Every use case is checked against a quote from it.
How to install Orbit MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Orbit MCP in Claude Code
$ claude mcp add orbit -- npx -y @orbit-tools/cliInstall Orbit MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"orbit": {
"command": "npx",
"args": [
"-y",
"@orbit-tools/cli"
]
}
}
}Install Orbit MCP in VS Code
.vscode/mcp.json
{
"servers": {
"orbit": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@orbit-tools/cli"
]
}
}
}Install Orbit MCP in VS Code CLI
$ code --add-mcp '{"name":"orbit","type":"stdio","command":"npx","args":["-y","@orbit-tools/cli"]}'Install Orbit MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"orbit": {
"command": "npx",
"args": [
"-y",
"@orbit-tools/cli"
]
}
}
}Install Orbit MCP in Codex
$ codex mcp add orbit -- npx -y @orbit-tools/cliInstall Orbit MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.orbit] command = "npx" args = ["-y", "@orbit-tools/cli"]
Install Orbit MCP in Gemini CLI
$ gemini mcp add -s user orbit npx -- -y @orbit-tools/cliInstall Orbit MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"orbit": {
"command": "npx",
"args": [
"-y",
"@orbit-tools/cli"
]
}
}
}Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubOrbit is a local-first runtime for coding agents. Keep using your authenticated agent CLI; Orbit adds a durable task queue, sandboxed worktrees, file locks for parallel runs, a gated delivery pipeline, and an audit log.
Why: fast agents make planning, review, and traceability easy to lose. Orbit keeps the prompt, plan, and review behind every change, with a task ID on every workflow commit.
- Single binary, no cloud. State lives in
~/.orbitand.orbit/; Orbit sends no telemetry. - Bring your own agents. Use the provider CLIs you already have authenticated, without giving Orbit API keys.
- MIT licensed. No paid tier or hosted offering.
How it works
You: The fsProfile lookup is undocumented. Get that fixed.
Agent: Files a proposed task with acceptance criteria. Approve it and ship?
You: Yes.
Agent: Queues it, then runs plan → execute → review in a locked, isolated worktree.
Opens a pull request. Review and merge it, then approve the task to close it.
Nothing starts without approval; PR runs stop for your review unless you authorize --complete. The task record keeps the prompt, plan, execution trace, and review. For larger specs, ask your agent to orchestrate: the bundled orbit-orchestrate skill splits the work, queues it once approved, runs it in parallel, and diagnoses failures (delivery workflows).
Platforms
| Platform | Support |
|---|---|
| macOS and Linux | Supported on x64 and arm64 |
| Windows | Via WSL2; not yet verified on a Windows host. Native Windows is not supported. |
Quick start
You need: a supported platform, Node 18+, an authenticated agent CLI, and authenticated gh for pull requests.
npm install -g @orbit-tools/cli
orbit init # machine name, task-ID prefix, agent skills, and Linux sandbox setup
Open your agent in the repo and ask it to “set up Orbit for this repo”. The bundled orbit-setup skill registers it, connects MCP, runs orbit doctor, and asks for choices such as the PR target branch. Start a fresh agent session, then ask: “Add a hello.txt file containing hello; file it as an Orbit task.” Approve and ship the task when prompted, review and merge the PR, then approve the task to close it. Watch with orbit web serve.
Prefer a plugin? Install Orbit for Claude Code, Codex, or Cursor. Every MCP tool has a CLI twin; for the same loop without an agent, see your first task from the terminal.
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, including MCP client files, before the first ship. Local delivery refuses tracked changes, merge conflicts, and untracked paths overlapping incoming changes.
orbit doctor checks CLI presence for default, system, and complexity-routed crews and warns when no MCP client is registered; it does not check provider sign-in or MCP connectivity. Use orbit doctor providers for all executor definitions. See Linux sandbox readiness and distro coverage.
| 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>) |
| Open the dashboard in a desktop window | Build the app in desktop/ |
| Pick the default crew (provider and model) | orbit config set workflow.default_crew <crew> |
| Route tasks to crews by complexity | orbit config set --global workflow.hard_complexity_crews '["opus"]' (more) |
| Upgrade | npm install -g @orbit-tools/cli@latest (orbit update --check shows what's new) |
Features
- Plan and govern: durable tasks, audit records, friction, and local search.
- Execute safely in parallel: sandboxes, locks, gated pipelines, and eight agent CLIs.
- Run unattended: bounded drains, optional completion, recurring reviews, and multiple machines.
- Observe and extend: dashboard, plugins, and bundled agent skills.
Crews and complexity routing
Crews name a provider, model, and effort level; complexity pools choose one for a task without an explicit crew. See crew definitions, init's seeded pools, and complexity routing, weighting, and overrides.
MCP and authority
Connect your agent explains operator and agent-only authority; federated MCP connects multiple machines.
Where state lives
Scoping rules explain machine and workspace state. See the runbooks for backups, recovery, and upgrades.
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
- docs/OPTIMISTIC_MERGING.md: the preferred delivery mode: merge fast, review after landing, keep the queue draining
- 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; bigger changes start with an issue. See CONTRIBUTING.md.
License
Orbit MCP questions
How do I add Orbit MCP to Claude Code?
Run claude mcp add orbit -- npx -y @orbit-tools/cli in your terminal. Add --scope user to make it available in every project.
How do I add Orbit MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Does Orbit require a cloud connection?
No, Orbit is a single binary that runs locally and sends no telemetry; all state lives in your local directory.
Do I need to provide my own API keys to Orbit?
No, you use your existing authenticated agent CLIs without giving Orbit your API keys.
How does Orbit handle parallel agent runs?
It uses file locks and sandboxed worktrees to prevent overlapping work and ensure safe execution.