Repolode
Submit
kunchenguid

kunchenguid/firstmate

An agent distro for running a crew of coding agents: you talk to one first mate that dispatches parallel tasks into isolated git worktrees and tmux-style sessions.

View on GitHub
Stars
8,661
Forks
2,716
Open issues
2,608
Last commit
yesterday

What is it?

firstmate is a portable directory of instructions, skills, and helper scripts that turns a general-purpose terminal coding agent into a coordinator for a team of agents. There is no app to install: you clone the repo, launch a supported harness such as Claude Code, Grok, Pi, Codex, or OpenCode inside it, and that session becomes the first mate. You describe work in chat, and the first mate spawns autonomous crewmates, each in its own visible session and clean git worktree, then supervises them until they produce a PR, an approved local merge, or an investigation report.

The project targets the situation where running several coding agents at once turns into manual babysitting: switching between terminals, copying context between repos, and losing track of which task failed. Supervision is event-driven, with a watcher that wakes the first mate only when a crewmate needs a decision. Each project can be set to ship via a PR, direct PR, or local-only merge, and optional persistent secondmates can run from isolated homes on the local machine or an SSH-reachable host.

The repo supports macOS and Linux, and several session backends including tmux as the reference default, along with herdr, Zellij, and others marked experimental.

Key features

  • 01Talk to one first mate that dispatches and supervises parallel crewmates.
  • 02Each task runs in its own disposable git worktree so parallel work on one repo does not collide.
  • 03Crewmates run in visible tmux windows or other supported session backends you can watch or join.
  • 04Per-project modes control whether work ships via PR, direct PR, or local-only merge.
  • 05Optional persistent secondmates can run from isolated homes locally or on SSH-reachable hosts.
  • 06Event-driven watcher wakes the first mate only when a decision is needed.

Use cases

  • Running several bug fixes or feature tasks across multiple repos at the same time.
  • Delegating codebase investigations or audits to agents and getting a written report back.
  • Driving a fleet of coding agents from a single chat session without juggling terminals.
  • Splitting larger workloads across persistent second mates on different machines.

Quick start

  1. 1

    Authenticate the GitHub CLI

    gh auth login
  2. 2

    Clone the firstmate repository

    git clone https://github.com/kunchenguid/firstmate
  3. 3

    Change into the cloned directory

    cd firstmate
  4. 4

    Launch a supported harness such as Claude Code; AGENTS.md takes over from there

    claude

Things to know

  • It is not a standalone app; it runs inside a supported coding agent harness such as Claude Code, Grok, or Pi.
  • It requires an authenticated GitHub CLI and tmux or another supported session backend.
  • Several backends and features, such as Zellij, cmux, and T3 Code, are marked experimental.

In collections

Tools for running coding agents in parallelMulti-agent orchestration frameworksClaude Code tools, skills & pluginsOpen-source AI agent frameworks & appsAI coding assistants & agents

Topics

#ai-agents#coding-agent#git-worktree#tmux#multi-agent#developer-workflow#claude-code#automation

FAQ

What is firstmate?
An agent distro for running a crew of coding agents: you talk to one first mate that dispatches parallel tasks into isolated git worktrees and tmux-style sessions. firstmate is a portable directory of instructions, skills, and helper scripts that turns a general-purpose terminal coding agent into a coordinator for a team of agents. There is no app to install: you clone the repo, launch a supported harness such as Claude Code, Grok, Pi, Codex, or OpenCode inside it, and that session becomes the first mate. You describe work in chat, and the first mate spawns autonomous crewmates, each in its own visible session and clean git worktree, then supervises them until they produce a PR, an approved local merge, or an investigation report.
Is firstmate free to use? What license does it have?
firstmate is open source under the MIT license. Check the license terms before using it in commercial products.
Is firstmate still maintained?
Actively maintained. The last commit to firstmate was on Nov 6, 2026.
What can I use firstmate for?
Running several bug fixes or feature tasks across multiple repos at the same time. Delegating codebase investigations or audits to agents and getting a written report back. Driving a fleet of coding agents from a single chat session without juggling terminals. Splitting larger workloads across persistent second mates on different machines.
How do I install firstmate?
Authenticate the GitHub CLI: gh auth login Clone the firstmate repository: git clone https://github.com/kunchenguid/firstmate Change into the cloned directory: cd firstmate Launch a supported harness such as Claude Code; AGENTS.md takes over from there: claude
Where can I get firstmate?
The source code and installation instructions are on GitHub: https://github.com/kunchenguid/firstmate

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects