Orbit — The engineering framework for your AI coding agents

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

Orbit brings engineering rigor to AI-assisted coding. Tasks for every change, ADRs for load-bearing decisions, structured audit of every tool call and provider exchange, conflict-aware parallel dispatch — local-first.

You drive Claude Code, Codex, or Gemini CLI against real code, often in parallel. Agents make it easy to skip the disciplines that keep code maintainable — no plan, no decision record, no audit trail, just prompt-and-merge. Six months later you can't reconstruct why an agent wrote a given line, and parallel runs collide because nothing reserved the files. Orbit makes those disciplines cheap and enforces them by default: tasks before edits, ADRs for load-bearing decisions, every tool call landing in a structured audit log, parallel runs sandboxed into worktrees with file-level locks. The constraints are the point — they're what keep agent-assisted code shippable at volume.

Primary 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/

• ADRs as first-class state. Capture load-bearing decisions as ADR artifacts with status lifecycle (proposed → accepted → superseded), owner, related_tasks/features, and supersession chains — authored and queried via orbit.adr.*, cross-referenced from task IDs and commit messages. → docs/design/adr-artifact/

• Auditability. Every tool call, provider request/response, and task transition becomes a structured, queryable event with agent identity attached — append-only, tamper-evident, exportable. → docs/design/auditability/

• Knowledge-graph–aware tooling. Agents query a parsed, content-addressed graph (symbols, imports, callers, implementors) instead of grep. Branch-scoped and safe for parallel rebuild; numbers in benchmarks/graph/. → docs/design/knowledge-graph/

• Conflict-aware parallel execution workflow For orbit run ship-auto, each agent run lands in its own git worktree per task, and the gate pipeline reserves task context_files as locks before fanning out, rejecting overlapping reservations up front instead of producing merge conflicts later. see merge-throughput. → docs/design/activity-job/

• Sandboxed-by-default execution. Dispatched agent CLIs run under an OS-level sandbox out of the box — FS access scoped to the worktree, network egress gated by per-activity policy. macOS only today (via sandbox-exec); on Linux/Windows the agent subprocess runs unsandboxed, with in-process FS guards still covering HTTP tools. → docs/design/policy-sandbox

Quick Start

Prerequisites: at least one supported agent CLI (Codex, Claude Code, or Gemini CLI), authenticated. For PR-based workflows (i.e., orbit run ship-auto), gh installed and authenticated; otherwise use --mode local.

# install
curl -sSf https://raw.githubusercontent.com/danieljhkim/orbit/agent-main/install.sh | sh
# or: brew install danieljhkim/tap/orbit
# or, in Claude Code:
#   /plugin marketplace add danieljhkim/orbit
#   /plugin install orbit

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

# launch interactive dashboard
orbit web serve

# create, approve, and ship a task
TASK_ID=$(orbit task add \
  --title "..." \
  --description "..." \
  --acceptance-criteria "..." \
  --workspace .)

# or simply ask an agent to create a task:
"Claude can you create an orbit task to refactor the authentication 
logic in ..."

orbit task approve "$TASK_ID"

orbit run ship-auto # conflict-aware, parallel flush of the backlog tasks to PRs

Full command reference: orbit --help and orbit-cli.com.

Semantic Search (optional)

Opt-in hybrid (embedding + BM25) search over task fields via orbit.semantic.search / orbit.semantic.related. Scope today is tasks only — graph, ADRs, learnings, and code are not indexed. The embedder runs as a separate companion subprocess, so semantic search has zero cost when unused.

orbit semantic install    # one-time: download companion + default model (bge-small)
orbit semantic reindex    # backfill existing tasks
orbit semantic search "race in the scheduler when locks overlap"

After install, task writes are embedded automatically in the background; reindex is only needed for the initial backfill. Companion + models live under ~/.orbit/embed/; the per-workspace index at .orbit/state/semantic.db.

Plugin vs CLI

Two install surfaces. Same binary and MCP tool surface underneath — the difference is what Claude Code wires up for you.

On Claude Code, install the plugin — it wires MCP automatically and ships subagents that don't exist on the CLI path. Add the CLI alongside if you also want the dashboard (orbit web serve) or terminal-driven workflows; the two share ~/.orbit/ global state.

On Codex or Gemini CLI, use the CLI install. orbit workspace init --mcp auto-detects installed MCP clients and registers Orbit with each; the MCP tool surface is identical, and orbit init seeds the skill set into the workspace.

Agent Tool Surface (MCP)

orbit workspace init --mcp registers the Orbit MCP server with the local agent CLI (Claude Code, Codex, Gemini). Names are canonically dot-separated (orbit.task.add); MCP clients that reject . see the underscored form (orbit_task_add) — both resolve to the same tool.

Substrate-internal namespaces (orbit.state.*, orbit.pipeline.*, orbit.policy.*, orbit.task.locks.*, orbit.graph.{add,move,write,delete}) are also registered but are called by the workflow plane, not by agent prompts. Full schemas are discoverable via the MCP tools/list call against the running server.

Workspace Layout (.orbit/)

orbit workspace init creates a .orbit/ directory at the repo root. All workspace state lives here — the directory is the source of truth, and removing it returns the workspace to a pre-init state.

.orbit/
├── tasks/        # task bundles (projections of ~/.orbit/tasks/workspaces/<workspace-id>/)
├── knowledge/    # parsed knowledge graph for this workspace
├── state/        # runtime state — append-only and rebuildable
│   ├── audit/         # append-only audit events (tool calls, transitions, provider I/O)
│   ├── job-runs/      # per-run metadata for each agent dispatch
│   ├── worktrees/     # worktree registry — tracks live agent sandboxes
│   ├── logs/          # agent + tool logs
│   ├── scoreboard/    # rolling counters (e.g. pr.json, task_review.json)
│   └── diagnostics/
├── resources/    # workflow definitions: activities, executors, jobs, policies
├── frictions/    # local friction log + tags.yaml
├── adrs/         # Architecture Decision Records (proposed/, accepted/, superseded/)
└── learnings/    # durable project learnings — pull-surface knowledge for agents

Three things to note:

• tasks/ is a projection. Canonical task bundles live under ~/.orbit/tasks/workspaces/<workspace-id>/<task-id>/ so they survive repo moves; .orbit/tasks/ is rebuildable from the canonical store. See docs/design/task-artifacts/.

Global state — credentials, the canonical task store, and cross-workspace config — lives under ~/.orbit/, created by orbit init. The recommended .gitignore pattern is .orbit/* with !.orbit/adrs/ and !.orbit/learnings/ un-ignored, so local runtime state stays out of the repo while project memory stays in.

Current Status

Orbit is v0.5.x — work in progress.

• Core local execution, graph build/query, and audit infrastructure are usable today.
• The execution substrate shows more internal machinery than the final product should; some historical CLI surfaces remain even though they're no longer central.
• Production or multi-machine deployments are not yet recommended.

Intentional technical debt on the path toward a tighter product focused on the audit and task layer.

Contributing

Contributions especially welcome on graph-aware scheduling, locking, worktree/session management, execution primitives, reconciliation, audit coverage, and tool-calling interfaces.

Before contributing: docs/design/CONVENTIONS.md and CLAUDE.md.

License

MIT