How to Stop Juggling AI Agents in the Terminal and Organize a Team with Firstmate

Familiar scene: you open five terminal tabs, each running its own coding agent. One fixes a flaky test, another rewrites components for dark mode, a third runs a dependency audit. Ten minutes later, chaos sets in. Which agent finished? Where did the tests fail? Which branch just got merged?

The firstmate project offers a different approach. Instead of manually controlling each agent, you communicate with one main assistant — the first mate. You hand tasks to them, and they distribute them to autonomous "sailors" in isolated environments.

What is an agent distro

The creators of firstmate describe their project not as another CLI utility or framework, but as an agent distro. Essentially, it's a portable set of instructions in AGENTS.md format, ready-made skills, scripts, and behavioral rules.

You clone the repository to your machine, run your familiar CLI tool inside it (such as Claude Code or Grok), and it dynamically picks up the logic for managing the entire team. No additional applications or heavy dependencies need to be installed on your system.

How the architecture works

The entire idea is built on responsibility separation and isolation of working spaces.

You give commands to the first mate through a single chat. For example: "review project xyz, fix the failing authorization test, and add dark mode."

The first mate clones the repository into the projects/ folder and creates tasks.

For each task, a separate terminal window is launched (tmux, zellij, cmux, or Orca) and an isolated git working tree is created using the treehouse tool.

Autonomous sailors work in parallel, without interfering with each other or breaking the main codebase.

After tasks are completed, the first mate collects the results and delivers a ready pull request or research report.

An interesting detail: the monitoring process doesn't consume neural network tokens. A background bash script monitors session state. It sleeps until an event occurs in one of the windows or a sailor needs a human decision. Only then does the observer wake up the first mate and passes them a brief summary.

Modes and commands

The project has built-in skills that are invoked directly from chat:

• /afk switches the system to away mode. The background process handles minor technical messages on its own, while genuinely important questions are collected into a digest and prepared for your return.
• /bearings generates a brief summary of all running tasks and active pull requests.
• /ahoy helps you quickly get up to speed by showing the event timeline and questions requiring your approval.
• /stow processes accumulated context, saves important knowledge to disk, and archives outdated data, saving token budget.

Beyond standard development with PR creation, firstmate has a research mode (scout). If you need to audit security or explore someone else's module rather than change code, the sailor will compile a detailed report in a Markdown file without modifying the repository.

Supported agents and launch

The repository is well-prepared for working with popular CLI tools. Claude Code, Grok, and Pi are officially recommended as the main first mate. Codex and OpenCode have also been tested.

Tmux is used as the default terminal backend, but zellij, cmux, and Orca are also supported.

Quick start looks like this:

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

After startup, Claude Code will pick up instructions from AGENTS.md, and you'll just need to greet it with ahoy!.

Who is this project for

If you only use AI assistants occasionally for minor refactoring of a single function, firstmate may seem excessive. But when actively working in parallel on multiple tasks, the project saves a lot of time. Isolation via git worktree prevents changes from being overwritten, and a single chat with the first mate eliminates the need to constantly switch between a dozen windows.