Help
FAQ
The questions people actually ask, answered without hand-waving. This is also where the storage internals get named precisely.
Where does my data live, exactly?
Three places, all inside your repository:
projects/<KEY>/tickets/<ID>.md: the tickets themselves, as plain Markdown. This is the canonical record..tracker/events/: an append-only JSONL event log. Every mutation lands here with its actor, reason, and timestamp..tracker/index.sqlite: a SQLite projection of the above, kept so boards, queues, and search answer instantly.
There is no hosted mode, no account, and no telemetry. Delete the directory and the data is gone; copy the repo and the tracker comes with it.
So SQLite is the database?
No, and the distinction matters. The Markdown files and the event log are the source of truth. The SQLite file is a disposable index: a cache with a schema. You can delete it any time; the next command rebuilds it from the files and says so once on stderr, or tracker doctor --repair does it on demand. Nothing the tracker knows lives only in the index, which is why the marketing page just says "lightweight" and leaves the engine name to this page.
What belongs in Git?
The record: ticket Markdown under projects/ and the event log under .tracker/events/. Keep the disposable parts out of version control: the index (.tracker/index.sqlite and its -wal/-shm companions) and the write lock (.tracker/write.lock). Dispatch also requires a clean workspace, so committing tracker state before dispatching is normal practice.
Can I edit the ticket files by hand?
Do not. Writes go through the CLI, web board, or MCP so the event log, the index, and lease state stay in agreement. If you already hand-edited something, tracker doctor --repair rebuilds the projection from Markdown and events and reports what it found.
How do I use Atlas on two machines?
The repo is the database, so Git movement moves the tracker with it. For tracker-aware transfer there are signed export bundles (tracker export create, tracker bundle), remotes and sync (tracker remote, tracker sync), and conflict tooling (tracker conflict). Sync operations are explicit commands, never background daemons. Automatic Atlas backup is a separate isolated Git remote you name; it is not a silent copy of origin and a push is not verified until Atlas checks the remote commit.
Do I wire each coding agent by hand?
No. After the binary is installed, tracker init in your project detects Claude Code, Codex, Cursor (including cursor-agent), OpenClaw, and Grok and writes Atlas-managed MCP entries named atlas-tasker plus the worker skill unless you pass --no-agents. Restart the client. Grok needs its own project-trust prompt before local skills appear. Atlas does not start those agents. A written file is not a live connection. Open that repo in the agent and ask for the current board. You do not run a second Atlas installer inside the agent. tracker integrations detect is the read-only version of that scan. The curl installer never initializes the directory it ran in; that stays tracker init.
Does setup turn on backup or a scheduler?
No. Local checkpoints start at tracker init unless --no-backup. A remote stays a named target you add first, then enable with tracker backup auto enable. tracker setup --yes is not backup consent. Neither init nor setup installs a user-level scheduler. The one-line installer places the binary; run tracker init in each workspace.
What platforms are supported?
The release installer covers macOS and Linux on arm64 and amd64, verifying checksums and GitHub build attestations on the way in. Building from source needs Go 1.26.6 or newer. Unstamped source builds report version: "dev" in tracker version --json, which is expected and harmless.
Can I put the web board on my network?
No. It binds to 127.0.0.1 only, with a per-process session token that is never written to disk, and --host refuses anything that is not loopback. The board has no user accounts, so non-loopback serving is not an escape hatch we offer. If you need a shared read-only screen, tracker web serve --read-only on a machine people can see is the sane middle ground.
How do agents fit without wrecking things?
Agents use the same commands and tools as humans, with guardrails that are structural rather than polite: illegal moves exit 4, leases prevent double work, review gates block completion, permission profiles can deny actions per agent, and the MCP high-impact tier needs a one-time human approval per call. The For agents page is the tour; MCP security is the fine print.
Who does Atlas attribute a CLI change to?
Mutation commands resolve an explicit --actor first, then TRACKER_ACTOR, then actor.default. If no valid identity is available, Atlas exits 2 before opening the workspace for a write; it does not silently choose human:owner. Add a reason whenever you mutate work. Tracked MCP writes and protected or security-sensitive CLI operations require one.
What do team presets change?
Pair and crossfire install review_gate with agent:reviewer-1; swarm uses agent:qa-1. New projects inherit that workspace policy. Applying a review preset also clears project open overrides so those projects inherit it, while preserving explicit non-open policies and reviewer overrides. The builder requests review and the required reviewer approves; approval itself moves review-gated work to Done.
Why are Done and Canceled separate?
They mean different things. The browser board keeps Canceled in a separate disclosure, and cards show their assignee. Terminal tables label each ticket with its status. A canceled ticket is terminal, but it does not satisfy dependencies or count toward Done totals.
Can I schedule a ticket in the past?
No. Setting or replacing a schedule requires a time strictly in the future and rejects the change before altering the schedule or assignment. A valid existing schedule can become overdue and then run through the normal tick flow.
How do I update or uninstall?
Run tracker update --check, then tracker update --yes to verify and replace the binary (or re-run the release installer). tracker uninstall previews Atlas-owned software and tracker uninstall --yes applies it. Boards, history, backups, and registry pointers stay. Removing the binary by hand also leaves repository data in place.
Something looks corrupted. Now what?
Run tracker doctor for the audit, then tracker doctor --repair to rebuild projection state. Exit code 7 from a read or from doctor usually means one of two things: the index is unreadable, or read-only doctor found it stale against the Markdown and events. A missing or stale index heals itself the next time a command opens the workspace; a corrupt one needs tracker reindex or tracker doctor --repair. Repair never invents data; it replays the Markdown and events you already have. It also will not recreate deleted worktrees, runtime files, or evidence artifacts, because those are execution leftovers, not the record.
Where is the complete reference?
The command reference lists every command and flag, including the governance, signing, backup, classification, and goal-manifest surfaces these docs only wave at. AGENTS.md is the same knowledge compressed for agent consumption.