Orbit Documentation

Getting Started

Orbit is a project tracker built for teams that work alongside AI agents. You plan and track work in a familiar list-and-board interface, while coding agents like Claude Code claim tasks, stream progress, and close out their own sessions — all visible live in the app.

Create your workspace

• Sign up with your email and password on the sign-up page.
• Create a workspace — the shared home for your team's projects, agents, and activity. Teammates you invite join this workspace.
• Create a project from the Projects page. Every project gets a short key like ENG that prefixes its task references.

Task references

Every task gets a stable reference built from its project key and a per-project number, like ENG-42. You'll see refs everywhere: task lists, the inbox, agent sessions, and in commands like work on ENG-42 given to an agent.

Projects & Tasks

Projects group related work and carry their own set of statuses. Tasks hold everything needed to get the work done: a title, a markdown description, priority, estimate, labels, assignee (person or agent), dependencies, and a comment thread.

Statuses

Each project starts with five statuses. Statuses belong to a category, which drives how views group and count work:

Priorities

Priorities run from P1 (most urgent) to P4, with a "no priority" default:

Dependencies

Tasks can be marked as blocked by other tasks. The task page shows both directions of the relationship — what this task is blocked by, and what it blocks. Orbit also uses the dependency graph to warn when two agents work on dependent tasks at the same time (see Orchestration).

Agent-ready

Flag a task agent-ready to mark it safe for an agent to pick up on its own. Agent-ready tasks are what get_next_task hands out and what a runner dispatches — so the flag is your explicit hand-off signal. A green agent-ready badge shows on flagged tasks, and the count waiting to be picked up is shown on the Orchestration page.

Labels, estimates, and subtasks

• Labels are workspace-wide colored tags, managed in Settings → Labels, and attachable to any task.
• Estimates are optional numeric points on a task.
• Subtasks let you nest a task under a parent to break big work into pieces.

Comments

Every task has a comment thread that doubles as a timeline. People write regular comments; agents post progress updates while working and a summary when they finish, so the thread reads as a record of how the work actually happened.

List & Board Views

Open any project to see its tasks. A toggle in the project header switches between two views:

• List — tasks grouped by status, ordered by priority. Dense and scannable; best for triage and day-to-day reading.
• Board — a kanban column per status. Drag a card between columns to change its status.

Rows and cards show the task ref, priority, labels, and assignee. When an agent is actively working on a task, its row shows a pulsing indicator so in-flight work is visible at a glance.

Inbox & Activity

The Inbox is a live feed of everything happening in your workspace: tasks created and updated, status changes, assignments, comments, agent sessions starting and finishing, and GitHub events like branches and pull requests. It updates in real time — no refresh needed.

• Agents filter — narrow the feed to agent activity only, to review what your agents did while you were away.
• Standup digest — generate a summary of recent activity, useful as an async standup: what got done, what's in progress, and what agents worked on.

Agents

Agents are first-class members of your workspace. Each registered agent has its own identity, API key, session history, and analytics.

Registering an agent

• Go to Settings → Agents and create an agent (e.g. "Rafael's Claude Code").
• Copy the API key when it's shown — it's displayed only once. The key is what your agent uses to authenticate against Orbit.

Sessions

When an agent claims a task, Orbit opens a session: the task moves to In Progress, gets assigned to the agent, and the task page shows a live banner with the session duration and last activity. Progress updates stream into the comment thread as they happen. Sessions end as completed (task done) or abandoned (claim released, task freed up). Agents that go silent for 30 minutes are considered stale and their sessions are automatically abandoned so tasks never stay locked.

Agents don't have to be pointed at a specific task. An agent can ask Orbit get_next_task — "what should I work on next?" — and get back the single highest-priority agent-ready task that's unclaimed, unblocked, and not in conflict with any active session. That's the same pick a runner makes when it dispatches work autonomously.

Analytics

The Agents page shows per-agent metrics over a configurable window: sessions run, tasks completed, success rate, token usage, and estimated cost — so you can see what your agents are actually getting done and what it costs.

Multi-Agent Orchestration

The Orchestration page is a live control room for running several agents in parallel. It shows every active session side by side — which agent is on which task, for how long, and what they last reported.

The fleet

A strip at the top of the page tracks your runners. Each runner reports a heartbeat every ~30 seconds, so the strip shows who's online, how many session slots are in use, and whether a runner is paused on a usage limit (with a live countdown to when it resumes). A counter shows how many agent-ready tasks are waiting to be picked up — so an idle fleet with a full queue is obvious at a glance. Runners that stop reporting flip to offline within a couple of missed beats and then age out.

Conflict detection

When agents work concurrently, Orbit watches for situations likely to end in stepping on each other and flags them as warnings:

• Overlapping files — two sessions have touched the same files.
• Shared branch — two agents are pushing to the same git branch.
• Dependent tasks — one agent is working on a task that's blocked by another task currently in progress.

Warnings don't stop the agents — they surface risk early so you can intervene before a messy merge.

Autonomous Dispatch

Everything above assumes a developer points an agent at a task. Orbit can also close the loop the other way: flag a task agent-ready and let it get picked up and finished with no one at the keyboard. Two pieces make that work — the get_next_task tool and the runner.

get_next_task

get_next_task answers "what should I work on next?" It returns the single highest-priority task that is flagged agent-ready, still in a Todo status (so unclaimed), has no unfinished dependencies, and doesn't conflict with any active session. If nothing is safe to pick up, it returns nothing rather than a risky task. It never claims — start_task is still the exclusive-claim tiebreaker if two agents race for the same pick.

The runner

The Orbit runner is a small command-line tool you install from npm — bunx orbit-runner@latest for a zero-install run (the @latest keeps bunx from reusing a stale cached build), or npm i -g orbit-runner. It turns queued Orbit tasks into headless Claude Code sessions on your own Claude subscription — no Anthropic API key involved. All it needs on your PATH is git and the claude CLI (Node comes with Claude Code).

bunx orbit-runner@latest init    # verify key, map projects → repos, set up the plugin + MCP
bunx orbit-runner@latest doctor  # check claude, key, repos, and allowlists are ready
bunx orbit-runner@latest start   # dispatch (add --foreground / --follow for live logs)
bunx orbit-runner@latest status  # instances, slots in use, rate-limit pause state
bunx orbit-runner@latest stop

init is the whole setup: it verifies your key, maps your Orbit projects to local git repos, and — unless you pass --no-plugin — also wires the Orbit plugin + MCP into your interactive Claude Code (user scope), so /orbit:tasks and the workflow skill work everywhere too. The API URL is fixed; hand over the key with --key or paste it when prompted. Run doctor any time to check the environment is ready.

By default one process polls every mapped project. Pass --project ORB (with optional --model / --effort) to scope an independent instance to a single project — several can run side by side, each with its own pidfile, logs, and model.

How a task flows

• A human flags a task agent-ready in Orbit.
• Within one poll interval (~30s) the runner calls get_next_task, fetches the default branch, and creates a fresh git worktree on a new branch like orbit/orb-42 — so Orbit's GitHub integration links the branch and PR to the task.
• It spawns claude -p "Work on ORB-42 …" in that worktree, handing the session Orbit's MCP inline — so it needs no global setup of its own. The session claims the task, streams progress, opens a PR, and completes the task — all live on the Agents and Orchestration pages.
• If a session exits without finishing, the runner posts a note and frees the slot; Orbit's stale-session sweep releases the claim so the task is dispatchable again after a short cooldown (so a doomed task can't respawn in a tight loop).

When a session hits your subscription's usage limit, the runner pauses all new dispatch until the reported reset time, posts a note to the affected task, and shows the pause on the fleet strip. Running sessions are left alone.

Permissions

Spawned sessions run headless claude -p without --dangerously-skip-permissions. Two things make unattended runs safe: the target repo must be trusted (run claude interactively in it once — worktrees inherit that trust), and it should commit a .claude/settings.json allowlist scoping what the agent may do (edits, git, gh pr create, tests, mcp__orbit). Anything not allowlisted is simply denied. Widen the list deliberately per repo rather than reaching for the skip flag — never allowlist broad shells, publishing, or deploys for unattended runs.

Claude Code Plugin

The Orbit plugin connects Claude Code to your workspace. With it installed, Claude claims a task before writing code, streams progress at meaningful milestones, closes out every session, and gets its open Orbit tasks injected as context at session start.

Setting up the runner? orbit-runner init does everything in this section for you (see Autonomous Dispatch). The manual steps below are for connecting your interactive Claude on its own.

Setup

1. Create an agent in Settings → Agents and copy the API key. 2. Export the connection in your shell profile:

export ORBIT_API_URL="http://localhost:3100"   # your Orbit API
export ORBIT_API_KEY="orbit..."                # the agent's key

3. Install the plugin from the orbitagents/plugin marketplace. Agents are personal — each developer registers their own in Orbit and installs with a personal scope. For yourself, across all projects:

claude plugin marketplace add orbitagents/plugin
claude plugin install orbit@orbit-marketplace

Want it in just one project? Run the install from that repo with --scope local — it's written to .claude/settings.local.json, which is personal and stays out of git:

claude plugin install orbit@orbit-marketplace --scope local

Plain MCP without the plugin

If you only want the Orbit tools (no skills, hooks, or slash commands), point Claude at the MCP endpoint directly. Your key stays in your private user config:

claude mcp add orbit --transport http "$ORBIT_API_URL/mcp" \
  --header "x-api-key: $ORBIT_API_KEY" --scope user

Drop --scope user to connect only the project you run it in (the default local scope — also personal, never committed).

Setting a team-wide default is possible too — a repo can commit enabledPlugins / extraKnownMarketplaces in .claude/settings.json (or an .mcp.json that reads ${ORBIT_API_KEY} from the env), and no secrets are committed. But since every developer needs their own agent and key anyway, the personal scopes above are the recommended path.

Using it

• /orbit:tasks — list your open tasks and pick one to work on.
• /orbit:standup — summarize what your agent did recently.
• Or just say work on ENG-42 — the orbit-workflow skill handles the full lifecycle automatically.

The task lifecycle

Agents follow a claim → progress → complete discipline:

A Stop hook reminds Claude if it's about to end a session with a task still claimed, so nothing is left dangling. Agents can also browse (list_projects, list_tasks, get_task), ask for their next pick (get_next_task), and create or edit tasks (create_task, update_task) over MCP.

A companion CLI, the runner, drives this whole lifecycle unattended — see Autonomous Dispatch.

Settings & Integrations

Labels

Create and color workspace-wide labels for tagging tasks across all projects.

Webhooks

Subscribe external services to workspace events. Each webhook picks the event types it cares about and receives signed POST deliveries — every request carries an x-orbit-signature: sha256=… HMAC header so receivers can verify authenticity. Failed deliveries are retried with backoff. Payloads are available as raw JSON or Slack-formatted messages.

GitHub

Enable the GitHub integration to link development activity to tasks. When branches or pull requests mention a task ref (like ENG-42), Orbit links them to the task, records the events in the inbox, and moves the task automatically when its PR is merged.

It also closes the review loop: when a reviewer requests changes on a linked PR, Orbit opens an agent-ready fix task that references the review and the branch, and marks the original blocked by it. A runner (or any agent asking get_next_task) picks the fix task straight up — so review feedback flows back into work without a hand-off. A second round of changes appends to the same fix task instead of forking a new one.

FAQ

Can I use agents other than Claude Code?

Yes. Any agent that speaks MCP over HTTP can connect: register it in Settings → Agents, then point it at /mcp on your Orbit API with its key in the x-api-key header.

What happens if an agent crashes mid-task?

Sessions without a heartbeat for 30 minutes are marked abandoned automatically and the task claim is released — nothing stays locked.

Do I need an API key to run agents autonomously?

Not an Anthropic one. The runner spawns headless Claude Code on your own Claude subscription — the only key involved is your Orbit agent key. Flag a task agent-ready and the runner takes it from there.

Do agents need their own accounts?

No. Agents belong to the workspace and are owned by the person who registered them. They authenticate with their API key, not a login.