The firstmate field guide

A tutorial-style reference for running a crew of coding agents with firstmate, and for the AXI tools it is built on.

firstmate is Kun Chen's (@kunchenguid) "agent distro". It is a git repo you clone and then launch a coding agent inside. That agent becomes your first mate. You talk only to it. It spawns other agents (the crew), gives each one an isolated git worktree, supervises them without spending tokens, and brings you back finished PRs, approved local merges, or investigation reports.

Talk to one agent. Ship with a crew. — firstmate README

This guide was built on 2026-09-26 from three kinds of source:

• the firstmate repo: 801 commits since 2026-06-11, about 7.2k stars.
• the AXI ecosystem repos it depends on: axi, gh-axi, chrome-devtools-axi, tasks-axi, quota-axi, lavish-axi, no-mistakes, treehouse, gnhf.
• Kun's public posts about firstmate on X, March to September 2026.

Pick a path#

The 60-second mental model#

            you (the captain)
                  │  chat: requests, decisions, "merge it"
                  ▼
 ┌─────────────────────────────────────┐
 │ first mate      (the cloned repo)   │  reads projects, never writes them
 │ AGENTS.md + skills + bin/ scripts   │  writes briefs, backlog, state
 └──┬──────────────┬───────────────┬───┘
    ▼              ▼               ▼
 crewmate 1     crewmate 2 ...  secondmate     each in its own tmux window /
 (ship)         (scout)         (persistent)   Herdr tab + treehouse worktree
    │              │
    ▼              ▼
 PR / local     data/<id>/report.md
 merge

Five facts carry most of the design:

1. You have one interface. Crewmates never talk to you. Everything reaches you through the first mate, as outcomes and decisions, not mechanics.
2. The first mate never writes to your projects. Every change, even a one-liner, is a crewmate's job. It happens in a disposable worktree and is delivered by the project's chosen path (no-mistakes, direct-PR or local-only).
3. Authority is explicit. Nothing merges without your word, unless you have granted +yolo for that project. Unlanded work is never torn down.
4. Supervision costs no tokens. A bash watcher sleeps on the fleet and wakes the first mate only when something needs attention.
5. A restart loses nothing. All state lives on disk (data/, state/) and in the session backend. A new session reconciles from those.

What firstmate is not#

The README says firstmate is "not a model, not a harness, not a skill, not an MCP server, and not a CLI." It works with harnesses you already use (Claude Code, Codex, Pi, Grok, OpenCode, Cursor, omp) and session managers you already use (tmux, Herdr, Zellij, Orca, cmux). It also stays out of the validation business. no-mistakes owns validation, your forge owns CI, and you own merges.

How this guide is organised#

Press / anywhere to search.