Documentation

Orbit Documentation

Everything you need to track work with your team — and your agents.

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:

Backlog	Ideas and unscheduled work. Not yet committed.
Todo	Committed work that hasn't been started.
In Progress	Actively being worked on — by a person or by an agent.
Done	Finished work.
Canceled	Work that won't happen. Kept for the record.

Priorities

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

No priority	The default. No urgency signal.
Urgent	Drop everything. Blocking work or production issues.
High	Important — should be picked up next.
Medium	Normal planned work.
Low	Nice to have. Picked up when there's slack.

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).

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.

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.

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.

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.

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:3000"   # your Orbit API
export ORBIT_API_KEY="orbit..."                # the agent's key

3. Install the plugin from the rafaelszago/orbit-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 rafaelszago/orbit-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:

`start_task`	Claim the task before writing code. Moves it to In Progress, assigns the agent, and starts a live session the team can watch.
`update_progress`	Post a progress comment at meaningful milestones. Also acts as a heartbeat that keeps the session alive.
`complete_task`	Mark the task done with a summary of what was delivered, and end the session.
`abandon_task`	Release the claim without completing — the task is freed for someone (or something) else.

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) and create or edit tasks (create_task, update_task) over MCP.

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.

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 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.