First run and setup

The first time you open TaskTrooper, it takes you through a guided sequence at /setup before showing you the board. It has four steps, each unlocked only once the previous one has actually succeeded — not just been visited — so quitting mid-setup, restarting the app, or disconnecting something next week all land you back on the right screen with nothing stale to work around.

You can revisit an already-completed step at any time — to re-run the preflight, swap the connected agent CLI, or add another project — without losing your place in the sequence.

Check this Mac

This step runs entirely inside the desktop app: it probes your machine directly (installed binaries, signed-in accounts) through the Electron shell, so it cannot run in a browser tab. If you're looking at TaskTrooper's web UI without the desktop app behind it, this step tells you to download the Mac app instead of offering a button that could never work.

The checklist, in the order you should fix things:

Only agent-server and git are required; everything else is a capability that unlocks more of the product without ever stopping you from starting. Once every required item is green, Connect unlocks in the next step.

Connect an agent runtime

Agents do their work through a coding CLI running as a local process on this Mac, or through a model API. You need exactly one to get started:

• An agent CLI — Claude Code, Cursor, Antigravity or OpenCode. Pressing Connect verifies the binary is installed and signed in, then writes every enabled agent's role, rules and skills to disk in the layout that CLI reads. Only one local CLI can be connected at a time; connecting a different one disconnects the first.
• An API provider — OpenAI, Anthropic, Google Gemini, Groq, or any OpenAI-compatible endpoint (LM Studio, Ollama, vLLM, OpenRouter, or your own IP) with a base URL and key. These ask for no local binary at all.

Both live under Settings → LLM Connection if you want to add more later, or switch which one an individual agent uses — see Agent CLIs and API providers. That page has three sections:

Connecting a local CLI also writes every enabled agent's role, rules and skills to disk in the layout that CLI reads, so the moment it's connected your agents are ready to run through it.

Connect GitHub

Agents clone, branch, push and open pull requests as your GitHub account. You authorize this through GitHub's own permission screen — nothing is typed in by hand, and no personal access token ever passes through this step. Once connected, you can import private repositories the same way the setup sequence does.

GitHub also lives permanently under Settings → Integrations, alongside Vercel, Google Cloud and the mobile app stores, if you need to reconnect or switch accounts later.

Your first project

A project groups the repositories that ship together. This step:

1. Creates a project (a name is enough to start).
2. Imports a repository into it. TaskTrooper asks what kind of repository it is (backend, frontend, mobile, worker, monorepo — detected automatically from the working copy when it can tell), and profiles how it deploys and how it's built and tested.

You can add more repositories to the same project, or create more projects, at any time from Projects once setup is done.

What the app starts underneath

Opening TaskTrooper starts up to three local processes, in this order:

The backend brings up its own embedded Postgres (downloading the binaries on the very first start, as noted above). The window itself doesn't appear until the backend is answering, because the page reads its API address from the same process that started it — there's nothing useful to show before then.

Stopping the app stops the backend first (it may still hold agent sessions that are calling out to Appium), then Appium; the embedder is left running so a quick restart doesn't have to reload the embedding model.

The tray and the offline screen

TaskTrooper keeps running in the menu bar even when its window is closed — closing the window is not the same as quitting the app. Whether it starts the backend automatically on launch is controlled by an auto-connect setting (on by default). With it off, or if a required preflight item is missing, the window shows an offline screen naming the reason instead of starting anything, and you connect manually from there once it's fixed.

If the backend crashes or falls behind on its health check while running, the window reflects that as a degraded state rather than pretending everything is fine — the difference between "stopped" and "restarting, but not there yet" is exactly what tells you whether to wait or to go looking at logs.

Other integrations

GitHub is the only account setup asks you to connect, because it's the only one every task needs. Settings → Integrations also holds the accounts individual features need once you reach for them: Vercel (linking hosted projects for deploys), Google Cloud (reading Cloud Run services and GKE clusters), and the App Store Connect / Google Play credentials that sign and upload mobile releases. None of these block setup, and you can add them at any point later.

Resuming or redoing setup

Because every step's status is derived from the real thing it checks — whether a CLI is actually signed in, whether GitHub is actually connected — rather than from a "seen this screen" flag, there's nothing to reset by hand. Disconnect an agent CLI or a GitHub account from its own settings page and the corresponding step reports itself as not done again; reconnecting picks the sequence back up in the same place.

Once setup is complete, you land on the board — see Your first task to put it to work.