One workbench for your AI coding projects.
Plan, execute, track, and resume - without losing state.
Orbit is the project layer for AI coding tools. It works in Claude Code, Codex, OpenCode, and VSCode Copilot Chat - any tool that speaks MCP. Every orbit project gets a durable home: a plan, a living context file, and a task checklist. That state persists across sessions, survives context compaction, and reloads when you come back. On the Claude Code side, orbit also adds time tracking, a local analytics dashboard, autonomous execution, and a rich statusline; the other three currently get the project state and the MCP tool suite.
- Why Orbit
- Supported tools
- Install
- Upgrading
- Your First Project
- Features
- How Orbit compares
- Architecture
- Commands
- Documentation
- Contributing
- License
- Credits
Every orbit project lives under ~/.orbit/active/<project-name>/ as three markdown files: plan.md (the agreed approach, locked after approval), context.md (your decisions, key files, gotchas, and next steps as a living document), and tasks.md (a hierarchical checklist with progress). Sessions end, context windows compact, but your project state stays put. Run /orbit:go <project-name> in any new Claude Code session (or /orbit-go in Codex, OpenCode, or VSCode) and orbit reloads the full state. You pick up where you left off with your plan, your decisions, and your next steps already loaded.
Orbit tracks heartbeats while you work, aggregates them into sessions, and shows per-project, per-repo, per-day, and per-week breakdowns on a local web dashboard at localhost:8787. It merges orbit's own heartbeat data with Claude Code's JSONL session logs, so the picture includes time you spent in Claude sessions that were not formally tracked. You always know which projects are actually eating your cycles.
Orbit Auto runs project tasks in parallel with dependency-aware DAG scheduling, logs every iteration in real time, and streams execution state to the dashboard. You can watch the whole run as it happens or walk away and check the iteration log afterward. Every task, every attempt, every outcome is visible.
Orbit exists because no single existing tool integrates all three. See How Orbit compares for the honest breakdown against the current field.
Orbit's MCP server and slash commands install into any of the major AI coding tools. The full installer detects which tools you have and asks per-tool whether to register Orbit. Each prompt installs both the MCP server and the slash commands together; the CLI offers --no-codex-commands (and --no-opencode-commands / --no-vscode-commands) if you want MCP without slash commands.
| Tool | MCP server | Slash commands | Invocation | Hooks / statusline / orbit-auto |
|---|---|---|---|---|
| Claude Code | yes | yes | /orbit:go, /orbit:save, ... |
yes (full) |
| Codex CLI | yes | yes | /orbit-go, /orbit-save, ... |
not yet |
| OpenCode | yes | yes | /orbit-go, /orbit-save, ... |
not yet |
| VSCode (Copilot Chat) | yes | yes (macOS) | /orbit-go, /orbit-save, ... |
n/a (editor-level) |
Claude commands use : namespacing because Claude's plugin system auto-prefixes plugin commands. The other three tools have flat slash-command namespaces, so orbit's commands ship as orbit-go.md etc. and resolve to /orbit-go. The behavior is identical across tools - only the invocation token differs by one character.
Per-tool registration details:
- Codex - registered as a real plugin via
codex plugin marketplace add ~/.orbit/codex-marketplace. The[plugins."orbit@orbit"]stanza lands in~/.codex/config.toml. Restart Codex to load the commands. - OpenCode - markdown commands written directly to
~/.config/opencode/commands/. Picked up immediately, no restart needed. - VSCode - prompt files written to
~/.orbit/vscode/prompts/and registered in usersettings.jsonviachat.promptFilesLocations. Available across every workspace, no per-repo opt-in required. macOS only for now (Linux/Windows VSCode app detection deferred).
Per-tool hooks, statuslines, and orbit-auto integration stay Claude-only for this release - tracked as a follow-up phase post-launch.
Orbit ships in two flavors. Pick based on whether you want the full workbench experience (recommended) or just the plugin core.
One command, no clone needed:
uvx orbit-install
# or
pipx run orbit-installThe interactive wizard asks which components to install (default is all) and sets up:
- The orbit plugin itself (slash commands, MCP server, hooks, rules)
- The local dashboard at
localhost:8787as a background service (launchd on macOS, systemd on Linux) - The
orbit-autoCLI for autonomous execution - The
orbit-statuslineentry point, wired into~/.claude/settings.json - Orbit rule files under
~/.claude/rules/ - The
/whats-newand/optimize-promptuser-level slash commands under~/.claude/commands/
For a fully non-interactive install, use uvx orbit-install --all --yes. To install everything except specific components, combine --all with opt-outs (e.g. uvx orbit-install --all --yes --no-statusline). Opt-out flags on their own drop you into the interactive wizard; they only take effect alongside --all or explicit opt-ins.
Requirements: Python 3.11+, Claude Code CLI, and uv on your PATH (provides uvx). If uvx --version fails, install uv first with pip install uv or curl -LsSf https://astral.sh/uv/install.sh | sh. pipx works in place of uvx if you prefer.
Windows note: Windows service registration is not yet supported - the installer still registers the plugin, pip-installs orbit-auto, and prints manual instructions for running the dashboard.
If you only want the plugin core (slash commands, MCP tools, lifecycle hooks, orbit rules) and don't need the dashboard, orbit-auto CLI, or statusline, install Orbit as a pure Claude Code plugin via the marketplace.
In Claude Code:
/plugin marketplace add tomerbr1/orbit-pm
/plugin install orbit@orbit-pm
Restart your Claude Code session.
Requirements: Claude Code with uvx available on PATH. If uvx --version fails, install uv first with pip install uv or curl -LsSf https://astral.sh/uv/install.sh | sh. The MCP server and bundled orbit-db are built on demand; no manual pip install is needed.
What you give up with the plugin-only install: no local dashboard at localhost:8787, no orbit-auto CLI for parallel execution, no rich statusline. You keep everything else: per-project plan/context/tasks files, /orbit:go resume, time heartbeat tracking in ~/.orbit/tasks.db, and all 30+ MCP tools.
The full installer also registers orbit in any non-Claude tool it detects. See Supported tools above for the per-tool registration mechanics. The MCP server and slash commands are the same files orbit ships to Claude; only the invocation token (/orbit:go vs /orbit-go) differs.
Re-run the installer to refresh every component to the latest published version:
uvx orbit-install --updateThis pulls the latest orbit-dashboard and orbit-auto from PyPI for the components you originally installed, restarts the dashboard service, and reinstalls the Claude Code plugin. The MCP server (mcp-orbit) runs through uvx --from ${CLAUDE_PLUGIN_ROOT}/mcp-server, so it refreshes from whatever the plugin marketplace pulled in. Run /plugin update orbit@orbit-pm in Claude Code (or claude plugins install orbit@local for maintainers) if you want to force a plugin-cache refresh. Restart your Claude Code session to pick up the new plugin code. orbit-db is a transitive dependency of orbit-dashboard and orbit-auto, so it refreshes alongside them.
If the uvx cache is pinning you to an older orbit-install itself, clear it with uvx cache prune or uvx --refresh orbit-install --update.
From Claude Code:
/plugin update orbit@orbit-pm
Restart your Claude Code session.
If you are developing on orbit rather than consuming it, see CONTRIBUTING.md for the uvx orbit-install --local workflow. A git pull picks up changes in the editable Python packages; you still need claude plugins install orbit@local for plugin-cache refreshes and a service restart for dashboard server-code changes.
/orbit:new auth-refactor
Orbit drops three files under ~/.orbit/active/auth-refactor/:
auth-refactor-plan.md # the agreed approach, locked after you approve
auth-refactor-context.md # living notes: decisions, key files, gotchas, next steps
auth-refactor-tasks.md # checklist with hierarchical subtasks
Claude walks you through a clarifying conversation, proposes a plan, and asks for approval. Once approved, the plan file is locked and the context file starts tracking your real progress.
Edit files, run tests, make decisions. Orbit tracks time in the background via heartbeats. When Claude Code compacts the context window, orbit's PreCompact hook auto-saves your current state so nothing gets lost.
If you want to checkpoint manually at any point:
/orbit:save
/orbit:go auth-refactor
Orbit reloads the plan, context, and tasks files and shows you:
- Where you left off (from the context file's "Next Steps" section)
- Progress (X/Y tasks complete)
- Key architectural decisions you made
- Any gotchas you flagged
You pick up without reconstructing anything.
Requires the full install (uvx orbit-install). If you picked the plugin-only install, skip to "Finish it".
If your tasks are decomposed enough, hand the whole project to Orbit Auto:
orbit-auto auth-refactor # parallel, 8 workers (default)
orbit-auto auth-refactor -w 12 # 12 workers
orbit-auto auth-refactor --sequential # one task at a time
orbit-auto auth-refactor --dry-run # show execution plan without runningAuto runs each task in a separate Claude Code invocation, respects task dependencies, and streams iteration events to the dashboard.
/orbit:done auth-refactor
Orbit archives the project files to ~/.orbit/completed/ and records the final time and progress stats.
That is the full lifecycle. Everything else is optional depth.
Every project has three markdown files: plan, context, and tasks. They live under ~/.orbit/active/<project-name>/ and are fully human-editable. Plan captures the agreed approach and locks after approval. Context is a living document for decisions, key files, gotchas, and next steps. Tasks is a hierarchical checklist with per-item progress tracking.
Orbit's PreCompact hook auto-saves project state before Claude Code compacts the context window. When you run /orbit:go in a new session, the full state reloads. You never reconstruct your mental model from scratch, and you never lose a decision you made three sessions ago.
A FastAPI + vanilla JS single-page app at localhost:8787. Shows active and completed projects with time tracking, per-repo breakdowns, hourly heatmaps, a weekly activity view, Orbit Auto execution monitoring with DAG visualization, and untracked Claude Code sessions alongside the tracked ones. Dual-database under the hood: SQLite for writes, DuckDB for analytics reads.
A standalone CLI that runs a project's tasks to completion in parallel. DAG scheduling respects task dependencies so dependent work waits for its prerequisites. Default eight workers, configurable with -w N or --sequential. Every iteration is logged with a timestamp, the task, the agent that ran it, and the outcome, and streamed live to the dashboard.
An optional terminal display showing the active project with progress fraction, git branch and status, Claude model, context usage, API limits, and last action time. OSC 8 hyperlinks open directly into the dashboard's project view from your terminal. Configurable, dark-mode friendly, low-latency.
Orbit's MCP server exposes tools across five categories: task lifecycle, file operations, time tracking, iteration logging, and repository management. Claude uses them automatically during /orbit:new, /orbit:go, and other commands, but you can call any of them directly if you want fine-grained control.
Three Claude Code hooks tie orbit directly into the session lifecycle, and they are what makes "resume tomorrow" actually work. SessionStart auto-detects the active project as soon as you open a terminal. PreCompact auto-saves your context before Claude Code compacts the window, so nothing gets lost on long sessions. Stop reminds you to run /orbit:save if you edited project files without saving. All three ship with the plugin.
Orbit sits at the intersection of three categories that usually ship as separate tools: task management, context preservation, and execution with analytics. Here is an honest look at how orbit stacks up against the current field, grouped by category so you can jump to the tool you already know.
For readers who know the Anthropic Productivity Plugin or Taskmaster AI:
| Capability | Orbit | Productivity Plugin | Taskmaster AI |
|---|---|---|---|
| Auto task decomposition from PRD | manual (Claude-assisted) | manual | yes (dependency-aware) |
| Plan + context + tasks files per project | yes | partial (tasks only) | no |
| Resume project across sessions | yes (/orbit:go) |
yes (workplace memory) | yes (file-based JSON) |
| Time tracking per task | yes (heartbeats) | no | no |
| Local dashboard | yes (web, analytics) | yes (HTML Kanban) | no |
| Autonomous execution | yes (orbit-auto) | no | no |
| Build/test gates on task close | no | no | yes |
| Multi-IDE support | Claude Code, Codex, OpenCode, VSCode (MCP) | Cowork-first | 13 IDEs |
| License | MIT | Anthropic official | MIT + Commons Clause |
Honest takeaway: Taskmaster is stronger at PRD decomposition and at working across multiple IDEs. The Productivity Plugin is the simplest official option, with a Kanban board and workplace memory, and it ships from Anthropic. Orbit is the only one of the three with per-project time tracking, a local analytics dashboard, and autonomous execution in the same tool.
For readers who know claude-mem or MemPalace:
| Capability | Orbit | claude-mem | MemPalace |
|---|---|---|---|
| Unit of organization | Projects | Sessions, entities | Wings, rooms (domains) |
| Capture mode | On compaction + /orbit:save |
Auto per session | Auto every 15 messages |
| Storage | Human-editable markdown | AI-compressed, vector search | Structured memory palace |
| Project-scoped state | yes (plan, context, tasks) | partial | partial (wings can be projects) |
| Task checklists with progress | yes | no | no |
| Time tracking | yes | no | no |
| Dashboard | yes | partial (web viewer) | no |
| Autonomous execution | yes | no | no |
| Cross-domain recall across projects | partial | yes | yes (by design) |
Honest takeaway: claude-mem and MemPalace are genuinely better than orbit at cross-project memory recall. They auto-capture and query across everything you have ever worked on. Orbit is better at project-scoped state: what is the plan for this project, what have I decided, what is the task list, how much time have I spent, what is next. You can reasonably run orbit alongside a memory layer: MemPalace or claude-mem for long-term cross-project recall, orbit for the project you are actively building.
For readers who know GSD or Superpowers:
| Capability | Orbit | GSD (v2) | Superpowers |
|---|---|---|---|
| What it is | Project system | Autonomous execution CLI | Methodology / skills framework |
| Prescribes a methodology | no (flexible) | yes (spec, research, execute) | yes (7 phases, TDD enforced) |
| Autonomous execution | yes (DAG, parallel) | yes (sequential phases) | partial (native Task tool only) |
| Context preservation across sessions | yes (plan/context/tasks files) | partial (fresh context per task) | no |
| Time tracking | yes (per project) | partial (cost and token tracking) | no |
| Dashboard | yes | no | no |
| Statusline integration | yes | no | no |
| Token efficiency | moderate | low (fresh 200K context per task) | low (around 10x Plan mode per HN reports) |
| Composable with orbit | N/A | conflicts (both own execution) | yes (Superpowers skills inside an orbit project) |
Honest takeaway: GSD pioneered the "fresh context per task" pattern and remains the reference for aggressive context-rot elimination. Superpowers is a methodology, not a system, and it composes with orbit: you can use Superpowers skills inside an orbit-managed project to get TDD enforcement and structured planning on top of orbit's project state and time tracking. Orbit's unique contribution is integrating autonomous execution with persistent project state and analytics in a single tool.
For readers coming from Claude Code Agent Teams, the native statusline, or Claude's built-in analytics:
| Capability | Orbit | Agent Teams | Native Statusline | Native Analytics |
|---|---|---|---|---|
| Status | Stable | Experimental (v2.1.32+) | Stable | GA (Teams / Enterprise) |
| Zero install | no (plugin) | yes | yes | yes |
| Persistent project state between invocations | yes (plan, context, tasks files) | no | N/A | no |
| Task list with dependencies | yes (DAG-scheduled) | yes (flat, shared) | N/A | no |
| Multi-session orchestration | orbit-auto (parallel, DAG) | yes (2 to 16 sessions) | N/A | no |
| Time tracking per project | yes (heartbeats, JSONL merge) | no | no | no (contribution metrics only) |
| Local dashboard with analytics | yes | no | N/A | cloud-only |
| Project-aware statusline | yes (OSC 8 deep links into dashboard) | no | generic (model, tokens, git) | N/A |
| Self-hosted | yes | yes | yes | no |
| Available to individual users | yes | yes | yes | Teams / Enterprise plans only |
Honest takeaway: Agent Teams is the most direct native competitor for the "run Claude autonomously across multiple sessions" use case. Its strengths are zero install and improving with every Claude Code release - that is a real risk to orbit over time. Its current limits: it is still experimental, it has no persistent state between invocations, no dashboard, no time tracking, no per-task analytics, and a 16-session ceiling. Native analytics is GitHub-scoped, cloud-hosted, and only on paid Teams or Enterprise plans. Orbit's statusline is project-aware with OSC 8 deep links into the local dashboard; the native statusline is a generic token/model/git display. Today orbit wins on persistence, analytics, and the integrated experience. If Agent Teams adds persistent state and a dashboard, that story gets harder - tracked as a known long-term risk.
Orbit is not the right answer for every workflow. Use one of these instead if:
- You want PRD to task decomposition with multi-IDE support: Taskmaster AI
- You want a methodology that enforces TDD and structured planning: Superpowers (and you can use it alongside orbit)
- You want cross-domain memory that outlives any single project: MemPalace or claude-mem
- You want aggressive context-rot elimination with fresh contexts per task: GSD / GSD-2
- You want Anthropic's official Kanban and workplace memory with zero setup: Productivity Plugin
- You want zero-install native multi-session orchestration with no persistent state between runs: Claude Code Agent Teams (experimental, ships with Claude Code)
- You want all of the above integrated into one workbench for a specific project: Orbit
Orbit's load-bearing piece is the mcp-orbit MCP server. Around it sit four standalone components you can install or skip independently:
| Component | Purpose | Installs via |
|---|---|---|
mcp-orbit |
MCP server (project state, file ops, time tracking, iteration logging) | Bundled with the Claude plugin; pipx install mcp-orbit for other tools |
orbit Claude plugin |
Slash commands as /orbit:*, lifecycle hooks (SessionStart, PreCompact, Stop), rules |
Claude Code plugin marketplace |
orbit-db |
SQLite + DuckDB layer at ~/.orbit/tasks.db |
pip install orbit-db |
orbit-auto |
Autonomous execution CLI (Claude Code only) | pip install orbit-auto |
orbit-dashboard |
Local FastAPI + vanilla JS web UI at localhost:8787 (Claude Code only) |
Runs as a launchd/systemd service |
orbit-statusline |
Optional multi-line terminal display (Claude Code only) | Bundled with orbit-dashboard, wired into ~/.claude/settings.json |
The MCP server plus orbit-db is the minimum viable install (and the only piece needed for Codex / OpenCode / VSCode). Everything else is opt-in, and each component can be used on its own if you only need that piece. orbit-db and orbit-auto are pip-installable packages you can depend on from your own scripts.
| Path | Purpose |
|---|---|
~/.orbit/active/ |
Active project files (plan, context, tasks) |
~/.orbit/completed/ |
Archived completed projects |
~/.orbit/tasks.db |
SQLite database (task tracking, time heartbeats, Claude session cache) |
~/.orbit/tasks.duckdb |
DuckDB analytics (synced from SQLite, dashboard reads) |
| Command | Description |
|---|---|
/orbit:new |
Create a new project with plan, context, and task files |
/orbit:go |
Resume work on an active project |
/orbit:save |
Persist progress before session end or compaction |
/orbit:done |
Mark a project as completed and archive |
/orbit:prompts |
Regenerate optimized prompts for subtasks |
/orbit:mode |
Assign workflow mode (interactive or autonomous) to tasks |
Deep dives for each component live in docs/:
- Installation - all three install paths (
uvx orbit-install, marketplace, manual), verification, uninstall, troubleshooting - Architecture - component boundaries, database schema, extension points
- Dashboard - screens, time accounting, API reference, customization
- Orbit Auto - sequential vs parallel, DAG scheduling, learning tags, worker model, review stages
- MCP Tools - all 30 tools by module, error handling, extension patterns
- Statusline - lines explained, env vars, customization, performance notes
- Hooks - SessionStart, UserPromptSubmit, PreCompact, Stop, state files, adding new hooks
Pull requests welcome. See CONTRIBUTING.md for development setup (uvx orbit-install --local), testing conventions, and PR standards.
MIT. See LICENSE.
Orbit stands on the shoulders of the tools that came before it. Direct inspiration and honest competition: GSD, claude-mem, MemPalace, Taskmaster AI, Superpowers, and the Anthropic Productivity Plugin. Each of them solves a real slice of the multi-session Claude Code problem, and orbit would not exist without the paths they blazed.