# [[Firstmate]] [repo](https://github.com/kunchenguid/firstmate) ![[Firstmate.svg]] Firstmate is an "agent distro" for running a crew of coding agents: a cloned repo of instructions, skills, scripts and state conventions that turns a general-purpose terminal agent (like Claude Code) into a supervisor. You talk to one agent, the first mate, and it does the rest: - spawns worker agents, each in its own terminal tab and its own isolated git worktree - supervises them until they're done - hands back finished PRs, approved local merges, or investigation reports It isn't a model, an app, an MCP server or a CLI. The repo itself is the distro: launching a supported agent inside it turns that session into the first mate, and makes you "the captain". ## How it works - There's one first mate session per setup. Starting a session in the repo takes a lock, and any second session opened there is read-only. - There are two kinds of job: - Ship (the default) changes code and ends in a PR or a ready local branch. - Scout is research, diagnosis, planning or an audit. It ends in a report at `data/<id>/report.md` and changes no code. - The first mate never edits projects itself. Workers do all project changes, and it never merges without your approval unless a project is set to allow that. - Projects are cloned into `projects/` inside the firstmate repo, so your own copies elsewhere (e.g. `~/git/<project>`) are left alone. - Workers never talk to you directly; everything goes through the first mate. You can type into a worker's tab and it counts, but it's usually easier to tell the first mate and let it relay. - Supervision is event-driven: a small background watcher wakes the first mate only when something needs attention, so idle waiting costs no tokens. - Everything important is saved on disk (task list, reports, decisions, worker records), so restarting the session is safe. ## Setup Requirements: - a supported agent ([[Claude Code]], [[Grok]], [[Pi]], [[Codex]], [[OpenCode]], [[Cursor]], [[Oh My Pi]]) - [[Git]] - the [[GitHub CLI]], and a terminal backend for the workers (tmux by default, or [[Herdr]], which is what I use). ```sh gh auth login git clone https://github.com/kunchenguid/firstmate cd firstmate claude ``` On first start it checks its toolchain and offers to install what's missing, only after you approve: - `treehouse` for isolated git worktrees - `no-mistakes` for the review/test/PR pipeline - `gh-axi` for GitHub - `chrome-devtools-axi` for browser work - `tasks-axi` for the task backlog - `quota-axi` for checking usage quota - `lavish-axi` for visual reports (optional) Restart the session after installing, since some of these tools only load in a fresh session. ### Adding a project Tell the first mate about it, e.g. "look at my project `defiantjazz`". It clones the project into `projects/` and registers it with a delivery mode: - `no-mistakes`: full review, tests and CI, then a PR - `direct-PR`: a PR without the pipeline - `local-only`: a local branch, no remote - `no-mistakes-prod-only` (the default for new remote projects): product changes get the full pipeline, internal tooling gets a direct PR Adding `+yolo` lets it merge green work itself. That's off by default. ### First-run gotchas (Claude Code workers) - The first worker launch shows Claude Code's once-per-machine "Bypass Permissions" warning. Its default is "No, exit", and firstmate can't move the selection, so accept it by hand in the worker's tab. Alternatively, put `auto` in `config/claude-permission-mode` so workers use Claude's auto mode and the prompt never appears. - A worker may also ask "Allow external CLAUDE.md file imports?". Answer it by hand. Don't press Escape: that records a permanent "no" for that project. ## Basic commands Slash commands in the first mate session: | Command | What it does | |---|---| | `/bearings` | Status digest: what's in flight, what needs you | | `/ahoy` | Recap of recent events, then walks through open decisions one by one | | `/afk` | Stepping away: it keeps supervising and gives you a summary when you're back. Add instructions after it (`/afk merge anything green`) for it to act on | | `/quiet` | Fewer interruptions while you stay in the chat. `/quiet off` ends it | | `/stow` | Saves what the session learned before a reset | | `/updatefirstmate` | Pulls the latest firstmate and restarts cleanly | After `/afk`, your next message ends away mode. There's no `/back`. The inbox works from any terminal, outside the session: ```sh ~/git/firstmate/bin/fm-inbox.sh note "also bump the Go version" # queue a note for the first mate ~/git/firstmate/bin/fm-inbox.sh status # what's happening, without interrupting ~/git/firstmate/bin/fm-inbox.sh ask "what's the k6 default VU count?" # side question, never touches the fleet ``` ### Clearing and restarting - Clear in place: `/stow`, then `/clear`. - Restart: `/stow`, then `/exit` (or Ctrl+D twice), then run `claude` again in `~/git/firstmate`. Add `--continue` to reopen the same conversation. - Close the old session before starting a new one, or the new one is read-only. - Workers keep running through a restart. Restart when the session gets long or sluggish, when switching to unrelated work, or after installing tools. ## Best practices - Name the project and the outcome you want, e.g. "in `defiantjazz`, make the clue order configurable". - Say whether you want a change or an answer. "Investigate", "compare" or "is it worth..." gets a research report instead of a PR. A report is never approval to build; it'll ask first. - Batch independent jobs. They run in parallel, each in its own worktree. - Give exact pointers: paths, note titles, meeting names, PR links. - Steer through the first mate rather than worker tabs. It adds your words to the worker's instructions. - Approve plainly: "merge it", "go with option 2", "no, keep it". - One-off exceptions need to be explicit ("edit this file yourself just this once"). They don't carry over to next time. - State preferences once (e.g. "planning docs go in my Obsidian vault") and they're saved in `data/captain.md` for future sessions. - Don't edit the firstmate repo's `projects/` folder by hand; it keeps those copies in sync. - Use `/afk` before stepping away, and `/stow` before clearing or restarting. %% # Excalidraw Data ## Text Elements ## Drawing ```compressed-json N4KAkARALgngDgUwgLgAQQQDwMYEMA2AlgCYBOuA7hADTgQBuCpAzoQPYB2KqATLZMzYBXUtiRoIACyhQ4zZAHoFAc0JRJQgEYA6bGwC2CgF7N6hbEcK4OCtptbErHALRY8RMpWdx8Q1TdIEfARcZgRmBShcZQUebR44gAYaOiCEfQQOKGZuAG0AXX4IXDg4AGUoqHFUUDBIdXTqiCJlaRS6hkIECgAhXGwAa2VSYQ5iAGE2fDZSbggAYgAzZZX2 yGwRQKyASSr9CpGBhEnp2Yl5gEYEK6u1iA3SLahd9L7B4dGJqZm5qHIOZhwXBPO4PJ4vfQAMUI+HwFRgwTmgg8oM2mWeewObCOAHUSOpuHxwOs0TtMX9sQh4YiJMiSKjHuiIQAlYStDjhHJoC78EmMsnpADyQOwahg3AuiUSvPupIx6UhnCgkNw+hh4rQAFYZWCmXtFVkyoQjNUeNLibL+fL9AAVLBQACCLS4EmCiygDPB5OBjsebAokhCxG4HCE sJ1cohAFExg6/QGg3NgSMqBGrRC4ymbfAmiMhGNPXqFeQMqyaahQ+GLcxsCNYQANbgAZgALHEeC3EgBOLsAdibFxbLc1A5lNbr+AAmtwAGxdxLaAAcTZnbc1vcXFx42otRjYBm4tQ69AIQmqF2JAF80170qz88QOcwueg8wWZcMSEaTYTzR1P8QFQIHA3A7v+pAkAAsmwxAIDGuCaMEwZoIsBBhB+EFfKch7EpAPRTMhr7KJouAABQ8BcvbULwlH URRVGoAumoAJRrJAzIIMoYbAnMpDEWRPBNtKvBCXRomMdoLEQFeN7oliRzClA7AAiGYb4DKiwlggHFjEwhAcMoOF1JAmQIUh3B/GevLrEQIFoJZCDWRAHCqtUDlOcIUBEByFmkFZuEQPowJHKQAByrm+f5xmBcFTDwYhCCEQ5MkWnYABWCDYNkZQuXA0GwfF5koWhjkWv0SmMDa+74EZHSwIgSJpFlylsbKzBQAY2YNWglbqQF0yDIl3Cofg6EBZ pBhlE1SmcMNJVOfgoSOs1lXVapsIpR0jjMGZxxKvakGZEIc2jaVHSaPpjgGQACoEixMJkYhzKZCXBjKhDMD0l36cohVDfZflnZAH2QSQcBsPpUA5SUcA/X9SWAzKmhsJgU3BM1nD5U0ehZLg+nSWA150IsMLhIel4gJeQA== ``` %%