Connect your agent to the work.

• CLI + --json

  Commands support a machine-readable JSON envelope, errors go to stderr as JSON, and exit codes 0 through 7 are stable. Non-interactive commands do not stop for input. The CLI page has the contract.

• MCP server

  tracker mcp serve --global --tool-profile workflow is the machine-wide server. Pinned --workspace remains. There is no HTTP listener or remote client. Every mutation still runs Atlas permission checks, the write lock, and event metadata. Cross-workspace writes need workspace_id.

• Self-describing

  Every tool declares its underlying_atlas_action and a json_schema_hash, and calls are validated against the schema before they touch the tracker. Unknown arguments are rejected at the boundary.

• Context budgets

  Responses are capped by default at 128 KB, 50 items per list, and a rough 4,000-token estimate. Paged tools take limit and cursor, and oversized results come back truncated with a hint to narrow the call.

1. read

   44 tools · the default

   Boards, queues, tickets, schedules, agents, goals, history, runs, evidence, handoffs, sync state, and plan or dry-run tools. No workflow mutations.

2. workflow

   +32 tools · 76 total

   The complete agent loop: create projects and tickets, edit, prioritize, label, assign, link, claim, heartbeat, move, comment, review, approve, reject, complete, manage agents and teams, schedule, add evidence, hand off, and acknowledge wake-ups. Ticket and event writes require an actor and reason; key/name-only project creation is the metadata-container exception.

3. delivery

   +4 tools · 80 total

   Dispatch a run, create a change, and sync provider-backed change and check status into the tracker.

4. admin

   +2 delivery tools · 82 total; +9 admin tools · 91 total

   Provider review and merge, gate waivers, sync push and pull, import, archive, compact, and worktree cleanup. Requires the danger flag and a one-time human approval per call.

See the tool groups and the complete workflow profile, or inspect your installed binary with tracker mcp tools --json --tool-profile workflow.

• Hidden by default

  High-impact tools are not just denied, they are invisible unless the server was started with --dangerously-allow-high-impact-tools and a profile that includes them. Agents cannot ask for what they cannot see.

• One-time approvals

  Each high-impact call needs an approval a human created outside MCP with tracker mcp approve-operation, scoped to one operation, one target, one actor, with a TTL. The call must echo the approval id and its exact confirm_text.

• Single use

  Approvals are consumed on execution and never replayed. Expired, mismatched, or already-used approvals fail closed, and Atlas rechecks normal policy immediately before running the action.

• Attributed writes

  Every mutation names an actor and a reason, which land in the append-only event log. When a ticket moved, you can always answer who, when, and why.

• Audited denials

  Denied high-impact attempts are recorded to a local security audit log under .tracker/runtime/mcp/, so a curious agent leaves a paper trail instead of a mystery.

• Boring config

  Local stdio only, pinned to an absolute binary path. No sh -c, no npx, no curl pipes, no config snippets from untrusted repos. The security docs spell out the rules.

1. 01

   Install and initialize

   The verified release installer installs the published binary (v1.16.0). Needs curl, tar, and gh. In an interactive terminal it may offer optional tracker init for the displayed current directory; the prompt defaults to No. Unattended installs and SKIP_INTEGRATIONS=1 skip it.

2. 02

   Teach the repository

   tracker init configures detected agents without a picker. Restart the client; Grok also needs project trust. Or run tracker integrations install later. The picker is tracker init --integrations or bare tracker integrations install.

3. 03

   Register MCP

   For MCP clients, register an absolute tracker path and pin the workspace. Choose workflow when the agent is expected to work tickets. A fresh existing directory can opt into initialization with --init-if-missing.

4. 04

   Verify the surface

   Open the client’s MCP status, then ask for atlas.agent.available or inspect the live profile with tracker mcp tools.

Install repository guidance

tracker integrations detect
tracker integrations install

# for scripts and CI
tracker integrations install --targets claude,codex,cursor,openclaw,grok,generic

Re-running is idempotent: Atlas updates only its managed blocks and generated files. Whole-file replacement remains opt-in behind --force.

Register the MCP server

tracker init writes user-scoped atlas-tasker as tracker mcp serve --global --tool-profile workflow for detected clients. Restart the client; a written file is not a live connection. Global and pinned serve default to workflow. Choose --tool-profile read or --read-only for inspection only. Grok setup adds --tool-name-style portable so it can load names such as atlas_status. Pinned --workspace snippets below are the advanced alternative.

/absolute/path/to/tracker mcp serve --global --tool-profile workflow

claude mcp add --transport stdio --scope user atlas -- /absolute/path/to/tracker mcp serve --workspace /absolute/path/to/repo --tool-profile workflow

codex mcp add atlas -- /absolute/path/to/tracker mcp serve --workspace /absolute/path/to/repo --tool-profile workflow

Run the first tool loop

• The working loop

  Call atlas.agent.available, then use atlas.ticket.claim, atlas.ticket.move, and atlas.ticket.comment. Request review with atlas.ticket.request_review. Under review_gate, approval by the required reviewer itself moves the ticket directly to Done; rejection sends it back to In Progress. Use atlas.ticket.complete for open-mode work or policies whose separate gates have passed; it cannot bypass review.

• New workflow coverage

  The profile also creates project containers and tickets, edits priority and labels, renews active leases, links dependencies, manages agent profiles, applies team presets, sets schedules, adds evidence, creates handoffs, and acknowledges wake-ups. See every workflow tool.

• Reason codes

  When nothing is available, tracker agent pending says why with stable codes: dependency_blocked, waiting_for_review, waiting_for_owner, not_ready_status, claimed_by_other, policy_blocked, agent_at_capacity, missing_capability. No guessing, no polling loops that spiral. A backlog ticket whose blockers are all done is never not_ready_status: when the last blocker of an agent-assigned ticket completes, Atlas promotes it to ready itself, and an unassigned one shows up in available as a claimable promote action (a human-assigned one surfaces in that human's queue instead).

• Wrong moves fail fast

  Illegal status transitions exit 4. Claiming a ticket someone else holds exits 4. That is the workflow enforcing itself, and the agent simply picks the next available item.