Concepts

Organization

The tenant. Members have one role — OWNER, ADMIN, MANAGER, DEVELOPER or VIEWER — enforced on every API call. Teams group members. Everything below belongs to one organization.

Project

One or more Git repositories. Projects come from the GitHub App, from repositories workers find on their disks, or are created by hand. A project with several repositories has a primary repository that holds the task state.

Task

A unit of work for an agent: a title, a prompt, optional background knowledge, a priority and optional dependencies on other tasks. Special kinds: review (review a branch without changing it) and plan (break a goal into up to 30 tasks). A task moves through an explicit state machine:

QUEUED → CLAIMING → PREPARING → RUNNING → VERIFYING → COMPLETED
                        │         │  ▲         │
                        │         ▼  │         └─► RUNNING (remediation)
                        │   WAITING_FOR_LIMIT / WAITING_FOR_INPUT
                        ▼         ▼
                     CRASHED → RECOVERY_REQUIRED / QUEUED (requeue)
any non-terminal → CANCELLED ; failures → FAILED

Worker

A native process on a machine with code and agents. It connects outbound over HTTPS and WebSocket, so no inbound ports are needed. It claims tasks with a lease that it renews with every heartbeat; if a worker disappears, its tasks are requeued from their last checkpoint.

Agent, provider, model

The agent is the coding CLI (Claude Code, Codex, Gemini CLI, OpenCode, Aider). The provider is where the model runs — by default the agent's own login (native:<agent>), or an add-on provider such as OpenRouter or Ollama. For each task the worker picks a compatible (agent, provider, model) target; agent and provider are independent choices.

Policy

Layered settings — platform defaults → organization → project → worker → task — for concurrency, agent and model preferences, fallback on limits, Git, verification, capability installs, approvals and the OS sandbox. Later layers override earlier ones. See Execution policies.

Capabilities

What agents and the orchestration platform can use beyond the agent itself: skills (instructions), MCP servers (tools), plugins (code at task hooks) and integrations. Each installation owns its registry.

Verification

After the agent finishes, the worker runs the project's checks. Every required check must pass; failures go back to the agent (up to maxRemediationAttempts), and then a person decides. A task is never complete because the agent says so.

Checkpoint

Progress saved in .agent-orchestration/ in the project and sent to the control plane. Recovery — after a crash, a lost worker or an exhausted context — continues from the last checkpoint.