Start

Getting started

Install Atlas once, then let your coding agent set up the project and read the board. Your tickets stay in plain files in your repository. Atlas needs no account or hosted service. The one-liner selects the latest published release.

The short path

Install Atlas once:

curl -fsSL https://raw.githubusercontent.com/myrrazor/atlas-tasker/main/scripts/install.sh | sh

In the project you want tracked, ask your coding agent:

Initialize Atlas Tasker in this project.

Atlas sets up the board, local checkpoints, and integrations for supported agents installed on your machine. Restart the agent to load the integration, then ask normally:

What's the current status of this project?

The Grok demonstration reads Atlas through MCP and shows the result in Grok’s terminal interface. A real Grok Build capture lives on the homepage Get started section.

Needs curl, tar, and GitHub CLI (gh). Attestation uses a local bundle; no GitHub login. The installer places the binary only. Run tracker init in each workspace, then restart detected coding agents so they load Atlas MCP. A written config is not a live connection.

Install

The one-line installer is the normal path. It fetches the latest published build (v1.16.0), checks its SHA-256 checksum, verifies the GitHub build attestation with a local bundle, and installs the tracker binary. Workspace initialization is a separate, explicit step. It needs curl, tar, and the GitHub CLI (gh); gh does not need a GitHub login. See verification results on the GitHub release page.

curl -fsSL https://raw.githubusercontent.com/myrrazor/atlas-tasker/main/scripts/install.sh | sh

go install github.com/myrrazor/atlas-tasker/cmd/tracker@latest

Go installs tracker into $(go env GOPATH)/bin unless GOBIN is set. Add that directory to your PATH.

Pin a specific release by exporting VERSION before running the installer. Unstamped source builds report version: "dev" in tracker version --json, which is expected.

Keep the binary current

Ask Atlas whether a newer release exists, then update when you are ready. The updater verifies the release checksum and GitHub build attestation before it atomically replaces the current binary.

tracker update --check
tracker update --yes

# install a specific release
tracker update --version v1.16.0 --yes

Initialize a workspace

Use a directory named app so init's default project key is APP. In any other directory, use the generated key instead. Init writes .tracker/, local checkpoints, and Atlas-managed MCP entries named atlas-tasker for detected agents unless you pass --no-agents / --skip-integrations. Detected agents are configured without a picker; --integrations opens the older TTY picker. Then tracker opens Home. Restart the coding agent; a written config is pending_client_restart until it does. Grok also needs you to trust this project in its own UI. There is no silent human:owner fallback on mutations.

mkdir app && cd app
tracker init
tracker

# skip agent MCP writes
tracker init --no-agents --no-open

Create a ticket

The app directory yields project APP. Extra projects are still tracker project create AUTH "Auth". Project keys are uppercase identifiers.

tracker ticket create --project APP --title "Ship first feature" \
  --type task --actor human:owner --reason "first ticket"
tracker ticket move APP-1 ready --actor human:owner --reason "groomed"

Two habits to pick up right away:

• Every mutation-flag command needs an identity. Atlas resolves an explicit --actor first, then TRACKER_ACTOR, then actor.default; if none is set, the command exits 2 before it writes. There is no silent human:owner fallback. Use human:<name> or agent:<id>.
• Add --reason so the audit trail explains why the write happened. MCP ticket and event mutations, protected operations, and security-sensitive operations require a non-empty reason; ordinary CLI mutations accept one whenever policy permits and should still receive one.
• tracker project create is the exception: projects are containers, not tracked mutations, so it takes neither flag. Passing --actor there is an unknown-flag error.

Open the board

tracker                  # Atlas Home on 127.0.0.1:7432
tracker board            # polished table; --style kanban for optional cards
tracker tui              # full-screen keyboard-first view
tracker web serve --open # single-workspace kanban

All three read the same tickets and enforce the same rules. The web board page covers the browser side in detail; the CLI page tours the whole command surface.

What just landed in your repo

projects/APP/tickets/APP-1.md   # the ticket. plain Markdown, readable anywhere
.tracker/events/                # append-only event log: who did what, when, why
.tracker/index.sqlite           # disposable query index. safe to delete

The Markdown files and the event log are the record. The index is a projection: if it is ever missing or behind, the next command rebuilds it from the files and says so once on stderr; tracker doctor --repair does the same on demand. Do not edit .tracker/ or ticket Markdown by hand; go through the CLI, web board, or MCP so the log, index, and lease state stay in agreement.

Ask the agent for the board

After init and the agent restart, you do not paste another installer into the coding agent. In Cursor, Claude Code, Codex, or Grok, open the project and ask:

What's the current status of this project?

A hooked-up agent runs tracker board or the MCP atlas.board tool and answers from the same tickets you just created. Atlas’s generated guidance explains how to read the board.

Connect agents in one pass

tracker setup refreshes the existing Atlas worker skill and, where the client supports it, registers a workspace-bound MCP server. It will not rewrite custom text outside the Atlas markers, and it will not rewrite an unmanaged MCP entry named like atlas-legacy.

tracker setup --plan
tracker setup --yes --agents generic

--yes applies the plan. It is not consent for backup, and it is not consent for machine-wide OpenClaw writes.

Optional Atlas backup

Tickets already travel with Git. Automatic backup is a second isolated Git repository for Atlas records. Local checkpoints live under $XDG_STATE_HOME/atlas-tasker/backups/<workspace-id>/. Atlas never selects origin for you. A successful push is not verified until Atlas fetches the remote commit into an empty temporary repository. Ticket writes stay available if backup is offline.

tracker backup target add --id private \
  --url git@github.com:you/atlas-backups.git \
  --acknowledge-data-boundary --attest-private
tracker backup auto enable --target private
tracker backup run --now

Neither tracker init nor tracker setup installs a user-level scheduler. That stays tracker backup schedule install --yes, then on Linux systemctl --user enable --now atlas-backup-<workspace-id>.timer. URLs with embedded passwords are rejected. Public GitHub remotes need an explicit public attestation plus --allow-public-github.

Where next

• Tickets and workflow: statuses, dependencies, reviews, and gates.
• Agents and dispatch: put an AI agent on the board.
• MCP setup: connect a compatible client to the typed local tool server.
• MCP tools: see what the read, workflow, delivery, and admin profiles expose.