Agents

Agents and dispatch

Atlas treats an agent run as a durable work record, not a chat transcript. Agents get registered, tickets get dispatched, progress lands as checkpoints and evidence, and handoffs carry context to the next actor. Everything stays inspectable after the session ends.

Register an agent

the roster

tracker agent create builder-1 --name "Builder One" --provider codex \
  --capability go --actor human:owner --reason "register builder"
tracker agent list
tracker agent eligible APP-1

The profile records routing metadata: provider, capabilities, and weights. It does not give Atlas control over Codex, Claude Code, or any other runtime; your agent still runs wherever it runs and drives the tracker through the CLI or MCP.

Or apply a team preset

tracker team turns a fresh workspace into a working agent team in one idempotent command: agent profiles, the implement-review runbook, a separation-of-duties permission profile, and the completion mode that makes gates real.

Preset	Roster	Completion
`solo`	builder-1	open: one agent finishes its own tickets
`pair`	builder-1 + reviewer-1	review gate with `agent:reviewer-1`
`swarm`	builder-1..3 + qa-1 + owner-delegate-1	review gate with `agent:qa-1`, routing weights, one active run each
`crossfire`	codex builds, claude reviews	review gate with `agent:reviewer-1` across vendors

apply one

tracker team list
tracker team apply pair --dry-run --actor human:owner --reason "preview"
tracker team apply pair --actor human:owner --reason "team setup"

Pair and crossfire set the workspace reviewer to agent:reviewer-1; swarm uses agent:qa-1. New projects inherit the workspace completion policy. Applying a review preset also clears existing project open overrides so they inherit the review gate, and its preview names every affected project. Explicit non-open completion policies and reviewer overrides remain in place. Re-running apply preserves existing agent, runbook, and permission-profile customizations.

The agent working loop

what agents actually run

# what can I work on right now
tracker agent available builder-1 --json

# take it and work it
tracker ticket claim APP-12 --actor agent:builder-1 --reason "start work"
tracker ticket move APP-12 in_progress --actor agent:builder-1 --reason "start work"
tracker ticket comment APP-12 --body "retry now exponential" \
  --actor agent:builder-1 --reason "progress note"

# hand it over
tracker ticket request-review APP-12 --actor agent:builder-1 --reason "ready for review"

# the configured reviewer finishes review-gated work
tracker ticket approve APP-12 --actor agent:reviewer-1 --reason "review passed"

agent available lists what an agent can start, continue, review, promote, or complete now, and each item includes suggested_commands ready to execute verbatim. Under review_gate, approval by the required reviewer moves the ticket to done; neither the owner nor reviewer can call complete from in_progress to skip that lifecycle. A promote entry is a backlog ticket whose blockers are all done; its first suggested command is the move to ready. When nothing is available, tracker agent pending builder-1 --json explains why with stable reason codes: dependency_blocked, waiting_for_review, waiting_for_owner, not_ready_status, claimed_by_other, policy_blocked, agent_at_capacity, missing_capability.

Only a dependency reaching done clears dependency_blocked. A canceled blocker stays blocking, on purpose, until a human resolves the plan. When the last blocker of an agent-assigned ticket completes, Atlas moves that ticket from backlog to ready itself (audited as agent:atlas) before the wake-up goes out. Nothing else is promoted: an unassigned dependent surfaces as a claimable promote entry in agent available and under unblocked_for_me in tracker queue, while a human-assigned one surfaces only in that human's queue/next under unblocked_for_me. An agent-assigned ticket shows as promote when the automatic move failed (wake-up metadata promoted="false") or the blocker was already done when it was linked or assigned.

Dispatch and runs

A run is the tracked container for one working session on one ticket: snapshot, worktree, checkpoints, evidence, and outcome.

dispatch lifecycle

tracker dispatch suggest APP-1          # who should take this, deterministically
tracker run dispatch APP-1 --agent builder-1 --actor human:owner --reason "start"
tracker run launch <RUN-ID> --actor human:owner --reason "prepare launch files"
tracker run open <RUN-ID> --json        # canonical runtime + worktree paths

Dispatch snapshots the run first, then creates a managed Git worktree so the agent works isolated from your checkout. It requires a clean workspace because of that worktree.
run launch writes brief.md, context.json, launch.codex.txt, and launch.claude.txt under .tracker/runtime/<run-id>/: everything a session needs to start with full context. It is idempotent; --refresh rewrites stale artifacts.
One active run per ticket is the default. dispatch run auto-routes only when exactly one agent is eligible; otherwise name the agent.
Cleanup is explicit and only allowed after a run completes, fails, or is aborted. Managed worktrees are execution isolation, never the source of truth.

Evidence and handoffs

prove the work

tracker run checkpoint <RUN-ID> --title "First pass" \
  --body "Health check route added." --actor agent:builder-1 --reason "status"
tracker run evidence add <RUN-ID> --type test_result \
  --title "Tests" --body "go test ./... passed" \
  --actor agent:builder-1 --reason "attach proof"
tracker run handoff <RUN-ID> --next-actor agent:reviewer-1 --next-gate review \
  --actor agent:builder-1 --reason "ready for review"

Evidence types include note, test_result, file_diff_summary, log_excerpt, screenshot, commit_ref, and more. --artifact copies a file into the run's evidence bundle.
Evidence is immutable: superseding creates a new item instead of rewriting history, and evidence survives run cleanup.
Handoffs are immutable Markdown packets with open questions, risks, and the next actor, stored under .tracker/handoffs/. Gates opened by a handoff show up in approvals and inbox until someone decides.

Assigned backlog also appears in tracker queue and tracker next under assigned_backlog, after ready and unblocked work. It remains pending with reason not_ready_status; seeing it does not claim it or move it to Ready.

Wake-ups

When a done ticket unblocks an agent's assigned work, Atlas records a wake-up. Agents acknowledge them explicitly, so nothing gets lost between sessions.

event-driven, not polling

tracker agent wakeups list builder-1
tracker agent wakeups ack <WAKEUP-ID> --actor agent:builder-1 --reason "resuming"
tracker agent auto set builder-1 --mode notify --actor human:owner --reason "wire wakeups"

agent auto defaults to notify. Command mode stores an argv list with the ticket id substituted in, and it refuses shell interpreters outright.

Teach your runtime the loop

tracker init detects installed coding agents, writes Atlas guidance, and configures their managed MCP entry. Restart the coding agent after setup. The release installer only places the binary. If stdout is a terminal and the current directory is already an Atlas workspace, it may offer tracker setup and defaults to no. Unattended curl | sh never initializes the directory it ran in. You can always install guidance later:

six repository guidance targets

tracker integrations detect
tracker integrations install

# explicit and non-interactive
tracker integrations install --targets claude,codex,cursor,openclaw,grok,generic

The six targets are Claude Code, Codex, Cursor, OpenClaw, Grok, and a portable generic integration. They write a generated guide plus runtime-specific skills, commands, or managed instruction blocks inside the workspace. OpenClaw follows that repository-local default too; writing its shared home-directory skill requires the explicit OpenClaw-only --global option. Re-running updates Atlas-managed content; --force whole-file replacement is opt-in. tracker init also writes Atlas-managed MCP entries unless you pass --no-agents. Restart the client. Follow MCP setup for pinned --workspace serve.