Run your crew
with mate.

Overview

mate is a single Go binary that runs AI coding agents as a team on your machine. There are four ideas to know:

You are the captain. You talk to the Mate. The Mate talks to the crews. The console is a narrow terminal panel that shows who is doing what and what needs your decision. Agents run inside Herdr, a terminal runtime for agents. The console opens any agent next to itself in your terminal, which must be WezTerm or Ghostty.

~/work/                        ← workspace
├── shop/                      ← a real git repo (the Mate never cds here)
├── blog/
├── .worktrees/shop-fix-cart/  ← crew fix-cart’s worktree, branch mate/fix-cart
└── .mate/                     ← all mate state
    ├── workspace.yaml   WORKSPACE.md   CREW.md   pricing.yaml
    └── projects/shop/
        ├── project.yaml   PROJECT.md   CREW.md
        ├── mate/          ← the Mate’s working folder: memory.md, backlog.md
        └── crews/         ← one folder per crew: brief.md, report.md, handback.md

A crew does one of two kinds of task:

• Ship: change code on a branch, then hand back with a handback.md acceptance table. It is finished when the branch is merged.
• Scout: investigate and write a report.md, with no code changes. It is finished when you accept the report. Durable findings go into PROJECT.md.

Install

Prerequisites

Install Beads with brew install beads and brew install dicklesworthstone/tap/bv, or use the release archives. Check them with bd --version and bv --version. mate never downloads executables for you.

Build mate

git clone https://github.com/nguyenngocanh94/mate.git
cd mate
make build                  # produces ./bin/mate
./bin/mate --version

Put bin/mate on your PATH, for example by symlinking it into ~/.local/bin. The console looks for herdr and fresh on your PATH and also in ~/.local/bin, /opt/homebrew/bin and /usr/local/bin.

Quick start

1. Create a workspace

   Copy

   mate init ~/work
   # initialized workspace at /Users/you/work

   This creates ~/work/.mate/ with workspace.yaml, WORKSPACE.md, CREW.md and pricing.yaml. Running it again on an existing workspace is safe.

2. Add a project

   A repo must be a Git repo inside the workspace. You can also clone one straight from a URL.

   Copy

   cd ~/work
   git clone git@github.com:you/shop.git
   mate project add shop shop
   # added project shop: repos=shop(shop@main) mode=local-only yolo=false
   
   # or: start with no repo, then clone one in
   mate project add blog
   mate project repo add blog https://github.com/you/blog.git

   A project can hold several repos. Each crew works in exactly one repo. You can also create a project from the console with n.

3. Open the console

   Open WezTerm or Ghostty, then run:

   Copy

   cd ~/work
   mate console        # console + agent column, built right away
   # or
   mate ~/work         # console; the agent column appears on your first Enter

   The console takes the narrow left column, about 20% of the window. The agent column on the right shows whichever Mate or crew you pick. On every open, the console also starts Herdr if needed, repairs moved paths, and resumes agents that were running before a reboot.

4. Start the Mate

   Select the project and press Enter to open it. Then press s to create the Mate, or to resume it. Pick the harness (Claude Code by default), then press Enter on the Mate’s row to open its terminal in the agent column.

5. Give it a task

   Type into the Mate’s pane like any chat, for example:

   you › Add a Buy button to the end of README.md linking to our checkout page.

   The Mate checks what it already knows, writes a brief and spawns a crew. If something is your call, such as which URL to use, it asks you first. The new crew appears in the console tree a few seconds later.

The console

The console is mate’s control panel. It never draws an agent’s terminal itself. It tells your terminal host to open that agent in the next pane. It is one stack of three panes: the list, a detail panel for the selected row, and the box with things waiting on someone. Press Tab to move between them.

Reading a row

• Status words are coloured only when they need you, for example needs-decision.
• ! and a number means that many items need attention under that row.
• Harness icons: ✻ Claude Code, ⌬ Codex. With a Nerd Font 3.5 they become the real logos.
• The footer shows what → next pane is currently showing, plus the keys that apply right now.

Keys

The mouse works too. Clicking a row is the same as Enter, clicking a pane’s rule focuses that pane, clicking [assign] hands an item to the Mate, and the wheel scrolls. To select text, use Shift+drag, which your terminal handles.

Actions by row

Working with your Mate

Talk to the Mate in its own pane: select its row and press Enter. Describe outcomes, not steps. The Mate owns everything inside the project: briefs, which crew and model to use, supervision and review. You own creating and removing projects, the mode, and merge permission.

What happens after you ask

1. Intake. The Mate checks its memory, PROJECT.md and earlier scout reports. If the project is new and unknown, it usually proposes an onboarding scout first, rather than guessing.
2. Brief. It writes crews/<id>/brief.md with your words verbatim, what is already known, what to build (and what is out of scope), acceptance criteria that each have a verify: step, and open decisions marked decides: captain or decides: mate. mate rejects a brief that is missing any of these.
3. Dispatch. It chooses a harness, model and effort from the dispatch table (see Configuration), then spawns the crew in a new worktree and branch.
4. Supervise. The crew reports in short status lines. Questions reach the Mate, or you.
5. Hand back. The crew writes handback.md or report.md. The Mate reviews it against your words and the acceptance list before it reads the diff, then reports to you.

Your standing rules

Write rules once and every agent follows them:

• .mate/WORKSPACE.md: rules for every Mate, for example “ask before adding a dependency”.
• .mate/CREW.md and .mate/projects/<p>/CREW.md: rules added to the end of every crew brief, for example “run make check before handing back”.
• .mate/projects/<p>/PROJECT.md: project context. The Mate maintains it from scout findings, and you can edit it.

Things the Mate is waiting on you for appear as news in the Mate’s detail panel. These are questions it asked and you haven’t answered yet, with their age. Answer them in the Mate’s pane.

Crew states

Each crew is in exactly one state, and only one party can set each state.

A crew never closes itself. Only mate crew stop (or a merge) ends a task. crew stop refuses while the branch has unmerged work unless you pass --discard. Stopped crews keep their folder under crews/<id>/, so reports and briefs stay readable.

Questions & the box

The box at the bottom of the console lists only unresolved items: a crew question nobody has answered yet, or a crew the console flagged as stuck. Each item says what it needs in plain words: needs an answer, stuck, quiet too long, agent gone, send wedged or over budget.

For each item you have two choices:

• Enter (or click): open that crew’s pane and answer it yourself, by typing one line.
• a or [assign]: hand it to the Mate. The Mate answers what is within its authority and asks you in its own pane about anything that is your call. If the Mate is busy, the item waits in a queue and is delivered as soon as its prompt is free. The row then shows assigned, queued and later assigned HH:MM.

An item leaves the box when the crew actually gets an answer or writes a new status. Press l to see the whole log, every status line and message, for debugging.

Review & merge

When a ship crew hands back, it moves to the Handed back group. The Mate reviews it and tells you it is ready. Then you can:

• See the diff: crew row → a → d, or mate diff <project> <crew> (--full for the whole patch).
• Read the report: e on the crew row, or mate report <project> <crew>.
• Talk to the crew: Enter on its row opens its pane, where you can ask for changes.
• Merge: crew row → a → M, or mate merge <project> <crew>.

mate merge only fast-forwards the crew branch into the repo’s default branch, and it never pushes. It refuses if the crew’s worktree has uncommitted changes, or if the branch needs a rebase. In that case the Mate asks the crew to rebase. A successful merge stops the crew and marks it finished.

By default only you can merge, and a merge requested by the Mate is refused. To let the Mate merge on its own, turn on yolo. The Mate picks up the change after it restarts.

mate project yolo shop on      # or off

For a second opinion, the Mate can start an independent reviewer with mate review <project> <crew> --id <reviewer>.

Manual & auto mode

Switch modes with m. Typing to the Mate yourself switches the project to manual, so a digest never talks over you. Once the Mate has replied and you have been quiet for 5 minutes, auto turns itself back on. If you chose manual with m, it stays manual. Every line the app types into the Mate starts with ⟦mate⟧, so the Mate can tell it apart from you.

Supervision and auto mode run inside the console process. Keep the console open while crews are working. With the console closed, nobody flags stuck crews and no digests are sent.

Task tracking

Each project has one Beads tracker at .mate/projects/<p>/.beads/ that holds epics, tasks, dependencies and priorities. The Mate uses it on its own: it checks for ready work, claims a task before dispatching a crew, links the crew to the task, and closes the task only after the work is merged or you accept the report.

• In the console, press t on a project to open Beads Viewer in a tab. In the viewer, E shows the epic tree, b the Kanban board, g the dependency graph, / searches and ? lists its keys.
• From a terminal, mate tasks shop opens the same viewer, and mate tasks shop --list prints the tasks.
• To change tasks by hand, use the wrapper. It locks the tracker for you:

mate beads shop -- create --title 'Checkout' --type epic --json
mate beads shop -- create --title 'Payment API' --type task --parent <epic-id> --json
mate beads shop -- ready --limit 10 --json
mate beads shop -- close <task-id> --reason 'Accepted delivery'

Everything after -- is passed straight to bd. To back up a project, copy the whole .beads/ folder. The JSONL export in it is not a backup.

Dashboard & Office

While the console is open, it also serves a read-only web dashboard at http://127.0.0.1:7777 and shows the address on its status line. To run the dashboard without the console:

mate dashboard ~/work --open                 # default 127.0.0.1:7777
mate dashboard ~/work --addr 127.0.0.1:7791

It updates live, and every number links back to the transcript line it came from. The dashboard only binds to localhost unless you pass --allow-remote. Be careful with that flag: the timeline quotes everything you typed.

To find out where tokens went, run mate usage shop --top 5 for the most expensive tasks, or mate usage shop <crew> --why for one task. Fill in prices in .mate/pricing.yaml to see costs; an unpriced model shows ?. To cap spending, set a budget in project.yaml. A crew over budget then shows up in the box.

Configuration

project.yaml

# .mate/projects/shop/project.yaml
repos:
  - name: shop
    path: shop               # relative to the workspace
    default_branch: main
mode: local-only
yolo: false                  # true = the Mate may merge on its own
mate:
  model: opus                # Mate model override (default: opus)
  effort: medium
  refresh_context: 150000    # auto context refresh threshold; -1 disables
budget:
  crew_tokens: 2000000       # 0 or absent = no limit
  crew_usd: 5
  project_usd: 50

The default harnesses for new Mates and crews are under defaults: in .mate/workspace.yaml (mate_harness: claude, crew_harness: codex).

Choosing crew models

The Mate picks each crew’s harness, model and effort from a dispatch table: small ships get a mid-size model, large or risky changes get the strongest one. To see the current table, run:

mate crew dispatch                                        # current rules
mate crew dispatch --example > .mate/crew-dispatch.json   # start your own

Your .mate/crew-dispatch.json replaces the built-in table completely. If the file is broken, all spawns stop until you fix it, so a broken table is never applied silently.

Environment variables

Command reference

Commands accept --workspace <dir>. Exit code 2 means a usage error.

For you

Used by agents

The Mate and crews call these from their panes. You rarely need them, but they are safe to run: crew spawn, send, peek, state, brief check|append, remember, memory check, recall, backlog, checkpoint, review, project facts, task-triage.

Troubleshooting