Install & first launch

Prerequisites, choosing a primary harness and backend, the launch command for each harness, and what happens on every session start.

There is no installer. You clone the repo and launch your agent inside it. From then on, AGENTS.md takes over.

1. Prerequisites#

• A verified primary harness: Claude Code, Grok, Pi (or pi-signed), Oh My Pi (omp), Codex, OpenCode, or Cursor Agent CLI.
• git and the GitHub CLI, authenticated: gh auth login.
• node.
• The CLI for your runtime backend. tmux is the default.

You do not need to install the rest yourself. At session start, bin/fm-bootstrap.sh detects missing tools, lists each with its install command, and installs only after you approve in that session. This is the full toolchain it checks:

You also need jq if you use dispatch profiles or Relay.

2. Pick a primary harness#

The README names Claude Code, Grok and Pi as equal co-primary recommendations. Pick the one that matches your subscription. They differ mainly in how supervision re-arms between turns:

Details per harness: Harness integration.

3. Clone and launch#

gh auth login
git clone https://github.com/kunchenguid/firstmate
cd firstmate

Then launch one harness from inside the checkout:

claude                                # Claude Code
grok --trust                          # Grok
pi                                    # Pi
FM_PI_HARNESS=pi-signed pi-signed     # signed Pi wrapper
omp                                   # Oh My Pi
FM_OMP_HARNESS=omp omp                # omp started from inside a Claude Code pane

4. Say ahoy#

> ahoy! look at my github project xyz, then fix the flaky login test and add dark mode

# firstmate checks its toolchain (asking your consent before installing anything),
# clones the project under projects/ and spawns two isolated workers.
# Minutes later:

  PR ready for review, captain: https://github.com/you/xyz/pull/42
  (fix flaky login test - risk: low - CI green)

> alright merge it

That exchange is the README's own example. The next page, Your first voyage, walks through it step by step.

What session start does#

Every session start runs bin/fm-session-start.sh once. It prints one ordered digest, headed SESSION START -, so the first mate can resume in one or two turns. The script's header names nine stages. The seven below carry the content. The other two are a read-once contract after step 4 and a closing reminder at the end.

1. Lock. It takes the per-home session lock (state/.lock) before anything mutates. If another live session holds it, this session is read-only: no spawn, steer, merge or repair.
2. Bootstrap. Detect-only checks always run: missing tools, harness, dispatch-profile validity, and "tangle" (the primary checkout left on a feature branch). When locked, the mutating sweeps also run: backlog reconciliation, secondmate convergence, secondmate liveness, pending remote-handoff retry, Relay artifact writes, and fleet sync.
3. Wake drain. It presents the durable wake queue (state/.wake-queue) as the first work of the turn, plus OPEN DECISIONS, UNREAD STATUS and RECORD DIVERGENCE sections.
4. Supervision instructions. It emits exactly one operating block for the detected harness, rendered from docs/supervision-protocols/.
5. Fleet digest. Backlog, every state/<id>.meta, a bounded tail of each status log, and alive/dead checks for each endpoint. It comes early so it survives if the harness truncates a long payload.
6. Network checks. GitHub auth, dead-secondmate relaunch, clone refresh. These are deferred so they never block the digest.
7. Context digest. data/projects.md, data/secondmates.md, data/captain.md, data/captain-shared.md and data/learnings.md. An ABSENT marker is meaningful: an absent captain.md means "use built-in defaults".

Diagnostic lines such as MISSING:, NEEDS_GH_AUTH or TANGLE: are handled by the bootstrap-diagnostics skill. See Troubleshooting.

The directory after first run#

firstmate/
├── AGENTS.md  CLAUDE.md  VISION.md  README.md      tracked contract and docs
├── bin/  .agents/skills/  skills/  docs/  tests/   tracked tooling
├── .env           LOCAL: Relay token, mail creds, TYPESAFE_API_KEY
├── config/        LOCAL: your operating choices (backend, harness pins, calm, ...)
├── data/          LOCAL: backlog.md, projects.md, captain.md, learnings.md, <id>/brief.md, <id>/report.md
├── projects/      LOCAL: clones of your repos (read-only to the first mate)
└── state/         LOCAL: <id>.status, <id>.meta, <id>.inbox/, locks, wake queue, away-mode records

Everything personal is gitignored, so you can pull updates to the distro (/updatefirstmate) without conflicts. See Configuration & state files.

Optional polish#

• /calm on Pi, or on Claude Code with CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1, hides firstmate's operational rows and shows an animated sailboat while it works. It changes presentation only. See Relay, voice & extras.
• Pi's /supervision-model pins a cheaper model and a shallower reasoning effort for the background supervision branch.