GitHub - gzurl/agent-squad: 👨🏻‍💼 You, the human, are the CEO of a team of Claude Code agents: 👷🏼‍♂️ a CTO plans, 👨🏼‍💻 a developer builds, and 👩🏼‍🔬 QA reviews every pull request on GitHub.

You, the human, are the CEO of a small software team of Claude Code agents. You decide what to build; a CTO plans it, a developer builds it, and QA checks every change before it is merged. The team comes to you when a decision is yours.

The agents run on Claude Code and coordinate on GitHub: issues hold the work to do, pull requests carry each change and its review, and milestones show how far along each goal is.

✅ Features

👥 A full team: a CTO, a developer and a QA, each in its own Claude Code session. You talk only to the CTO, in your own language.
🐙 Everything is on GitHub: the work in issues, each change and its review in a pull request, every decision in writing. A pinned plan issue shows the release live, row by row, so you can follow it from your phone.
🔍 Every change is a pull request that QA reviews before it merges.
🌳 Each agent works in its own git worktree, so nobody steps on anyone's files.
🔒 Rules enforced by scripts: checks before every push, nothing straight to main or to a release branch, no merge without QA's approval.
🧭 A live board, a Claude Code mod, above the CTO's prompt: what each agent is doing, and who waits for you.
☕ Step away and come back: pause the squad or leave it on autopilot, and get a summary when you return. Sessions keep the thread across compactions and restarts.
📈 Grows with you: several projects at once, token usage per agent, and upgrades in one command.
🏗️ Built by its own squad, which plans, writes and reviews every change.

👥 The team

👨🏻‍💼 CEO, you, the human. You decide what to build and why, and you only need to talk to the CTO. The agents write to you in your language, and to each other in English.
👷🏼‍♂️ CTO. Your partner on the product. It talks through with you what to build, helps you shape the vision and choose the stack, and plans the work as GitHub issues. It settles any disagreement between DEV and QA, and brings you the decisions that are yours, as options with a recommendation.
👨🏼‍💻 DEV. Writes the code and its tests, and opens a pull request for each issue.
👩🏼‍🔬 QA. Reviews every pull request in two ways: it reads the code, and it tests what the pull request says it does.

💬 What you see as the CEO

Each agent works in a session of its own; here, in cmux, the CTO's on the left and DEV's and QA's on the right. You talk only to the CTO.

The CTO reports to you in your language, one line per agent, and the line above its prompt shows what each agent is doing.

▶️ Quick start

You need Claude Code, a GitHub repository for your project, and the GitHub CLI (gh) logged in (Requirements has the details).

Install the squad. In your project's folder, run:
```
curl -fsSL https://raw.githubusercontent.com/gzurl/agent-squad/main/install.sh | bash
```
It installs the latest release, says what it did, and ends with the next steps below, your project's name in them.
Start three Claude Code sessions in your project's folder, each in its own terminal:
```
claude -n "CTO:<project-name>"
claude -n "DEV:<project-name>"
claude -n "QA:<project-name>"
```
If you like, give each session its colour on the squad board: /color yellow in the CTO's, /color blue in DEV's and /color green in QA's.
Tell the CTO: "Follow .agent-squad/playbook/BOOTSTRAP.md." It asks which language to use with you, finishes setting up the repository, asks you what it needs to know, and then asks what you want to build.

📔 Contents

I have been programming since I was seven (oh boy, those wonderful years of BASIC and assembler on an 8-bit ZX Spectrum!), and I have been a software engineer since 2003. Recently, generative AI has changed the way we build software forever. First came GitHub Copilot, with its auto-completed blocks, then ChatGPT, with snippets to paste into my IDE. Then came Claude Code, which hit like the meteorite that ended the age of the dinosaurs: the age of writing software by hand was over. Code was no longer my main value as an engineer. I had to raise the level where I add value: organising the AI's work, knowing what has to be done, why, and when to do it. It also meant learning to talk efficiently to the AI to really get what I want.

With Claude Code I went through several stages: a single session in the terminal, then desktop interfaces, then back to the terminal (iTerm2, then tmux, Ghostty, and finally cmux). Like everyone, I tried several agents on the same repository, each on its own feature, and then ran into the conflicts and the extra friction of managing Git worktrees. Several tools appeared to automate that, but I felt I was not getting all the developer experience that coding agents should provide.

Looking for that experience, I moved to two agents: a developer and a QA engineer. One builds, the other verifies. QA works from a different context, so it does not fool itself the way the developer would. That worked for a while, until I noticed I was spending too much time carrying one agent's decisions, plus my own feedback, to the other. The SendMessage tool, which lets sessions message each other, took me out of the middle (I was no longer the bottleneck-man-in-the-middle). But the experience was far from perfect: on a given feature, the two agents could not agree on whether the work was good enough (the famous P2s and P3s of one model reviewing another), and they would get stuck in a pointless loop that only burned tokens. That led to the last step: they needed a boss. Not me: an AI CTO.

That is how agent-squad's three-agent model was born. I play the CEO, or product manager, of a small team: a CTO, a developer and a QA. I only talk to the CTO, about vision, product, software stack, architecture and so on. Together we set the project's direction, and the CTO deals with the rest of the team and settles their disagreements. Each member works in its own local worktree, and the source of truth lives on GitHub, where I, as the CEO, can step in whenever I want. Every rule in SQUAD.md comes from something that went wrong on a real project, and the rules that matter most are enforced by scripts.

By the way, agent-squad has built itself: its own squad planned, wrote and reviewed it. I only set the direction.

agent-squad is my own, very personal take on how to build software today with Git, GitHub and Claude Code. I am sure it has plenty of flaws and limits. Try it, break it, and tell me what you think.

🔭 Overview

Built on Claude Code and GitHub

Claude Code runs the agents. Each agent is a Claude Code session named after its role and the project: CTO:<project-name>, DEV:<project-name> and QA:<project-name>. All three start in the project's main folder, which lets them share Claude Code's memory, and each works in a worktree of its own under .agent-squad/worktrees/. They send each other messages. Every session loads the charter through AGENTS.md, once: each worktree holds a copy of the project's instructions, which Claude Code would load again as an agent works there, so the installer has sessions leave it out. Hooks save the project's state before Claude Code compacts a session and hand it back afterwards. A session you resume, after updating Claude Code for instance, starts again in the main folder, and a hook reminds its agent which folder each agent works in.

GitHub holds the work. Issues are the backlog, grouped into milestones; pull requests carry the changes, and reviews carry QA's verdicts. While setting up, the CTO creates a set of labels the agents coordinate with: who owns an issue (CTO, DEV or QA), its type and priority, and its status (in progress, in review, approved or blocked). One more label, needs-ceo, marks what is waiting for you, so filtering by it gives you your inbox. The agents usually share one GitHub account, so they sign everything they write. Before a merge, a script asks GitHub, through gh, whether the pull request is really ready.

How the team works

sequenceDiagram
  actor CEO as CEO (you)
  participant CTO
  participant DEV
  participant QA
  CEO->>CTO: What to build, and why
  CTO->>DEV: An issue with acceptance criteria
  Note over DEV: Branch, code and tests,<br/>through the pre-push gate.
  DEV->>QA: A pull request that closes the issue
  loop Until QA approves the latest commit
    QA->>DEV: One review: the code read, the claims tested, a verdict
    opt Changes requested
      DEV->>QA: Fixes in one push, or evidence against a finding
    end
  end
  Note over DEV: Through the merge gate.
  DEV->>CTO: Merged into main
  CTO->>CEO: Done, ready for you to try

The CTO also writes pull requests of its own, reviewed by QA the same way, and settles any disagreement between an author and QA. Every rule, with its reason, is in SQUAD.md; the merge gate's exact conditions are in its §4.9. BOOTSTRAP.md is the CTO's one-time setup of a project.

When a session's context fills up

A Claude Code session has a limited context. When it fills up, Claude Code compacts it: it replaces the conversation with a summary, and whatever the summary leaves out is gone. Left to itself, an agent can come back from a compaction without knowing which pull request it was reviewing, or what it had promised another agent. agent-squad guards against that in three ways:

It steers the summary. AGENTS.md has a Compact instructions section that tells Claude Code what every summary must keep: the agent's role, the issue and pull request it is working on, the latest commit and verdict, the exact step it had reached, and anything it promised another agent.
It saves the facts and hands them back. Just before any compaction, manual or automatic, a hook saves a snapshot of the project's state in .agent-squad/handoff/: the worktrees, the open pull requests with their labels and verdicts, the issues in progress, in review or blocked, and the latest commits on the main branch. When the session resumes, another hook hands the snapshot back, with instructions to re-read the rules and the issue before doing anything else.
It keeps the real memory on GitHub. Each agent writes its state on its issue at every step, and long runs write a progress.log. What is written there survives any compaction; what was only in the agent's head may not.

What you can do: /context shows how full a session's context is. When a session passes about 90%, type /squad-save-state in it: its agent writes its state on its issue and tells you when it is ready. Then type /compact. If you type /compact without /squad-save-state right before it, a hook stops the compaction and says Save this session's state first: type /squad-save-state, then /compact.; a second /compact within ten minutes goes ahead anyway. A compaction you choose, at a quiet moment, loses less than one that Claude Code triggers in the middle of a task, which no hook can stop.

When you step away

One command tells the squad you are leaving, or that you are back. The CTO passes it on to DEV and QA, and answers you once for the three. Typed in DEV's or QA's session, it applies to that agent alone.

Type in the CTO's session	When	What happens
⏸️ `/squad-pause`	You need everything stopped at a safe point: to close the laptop, to use the machine for something else, or for any other reason	Each agent finishes what it is doing, saves where it is on GitHub, and stops. The CTO tells you when it is safe.
⏩ `/squad-autopilot`	You leave, and the machine stays on	The squad holds the course you set: the agents carry on with whatever needs no decision from you, and leave those decisions on GitHub for when you are back. Every half hour, the CTO checks that no work has stalled.
▶️ `/squad-resume`	You are back	The CTO sums up what was done, what waits for you, and the plan ahead. Paused agents pick up where they stopped.

Nothing notifies you while you are away: /squad-resume tells you what happened, and the issues labelled needs-ceo are your inbox.

The plan, pinned on GitHub. Each release in progress has a plan issue, pinned at the top of the repository's issues. It holds a table of the release: one row per issue, with where it stands and whose the next step is, then the release's own steps, such as your read of the README. The table changes whenever an agent changes the state of an issue or a pull request, and at every pass of /squad-watch, so that you can follow the release from your phone. /squad-resume shows you the same table. The plan issue also lists the release's issues as its sub-issues, up to the 100 GitHub allows, with GitHub's bar of how many are done, and each of them names the plan issue as its parent.

Whenever the CTO reports on the agents, during these commands or when you ask how they are doing, each agent gets a line of its own, always in the order CTO, DEV, QA, with an emoji for its state: working, paused, free, waiting for you, or no answer. The same lines come back in every update, so you see at a glance who is still busy.

Several squads on the machine? Add -all: /squad-pause-all, /squad-autopilot-all and /squad-resume-all, typed in any squad's CTO session, do the same for every squad, and you get one answer, grouped by squad, that names any squad that did not answer.

A session waiting for you in its own terminal, on a question or a permission, cannot act on a command until you answer it there, so the CTO tells you which one.

Work that stalls. An agent waits only for a message, and a message can go astray. /squad-watch, in the CTO's session, finds work whose next step has waited half an hour on an agent that sits idle: it pings that agent, and tells you if nothing has moved an hour later. A PR that QA approved but that still waits for a review requested on GitHub, such as a colleague's, is nobody's to merge yet: the watch tells you once it has waited an hour, since only you can reach that reviewer. It leaves out what already waits on you (needs-ceo) and what is blocked on purpose (status:blocked), and when it finds nothing, it says nothing more than the plan's table, which it updates and shows at each pass. /squad-autopilot runs it every half hour until you pause or resume the squad, and you can type it yourself at any time.

How many tokens the agents use

Type /squad-usage in any of the squad's sessions to see how many tokens each agent of the project has used: its input, the share of that input read from the cache, its output, and the models it ran on. /squad-usage 30d covers the last 30 days, and /squad-usage 2026-09-24 starts on that day. /squad-usage-all reports every project on the machine, one block per project, and asks no other squad: it reads every session's figures itself.

The figures come from the transcripts Claude Code keeps on your machine, which it deletes about 30 days after a session was last used. Each report also adds them to a history in .agent-squad/tokens.tsv, so they outlive the transcripts. Nothing leaves the machine. Tokens are not cost: most of the input is read from the cache, which is billed far below fresh input. When it finds neither transcripts nor history for the project, /squad-usage says where it looked, rather than report zero. On Windows, under Git Bash, it finds the transcripts by the project's Windows path.

The squad board

Above the prompt of the CTO's session, between two blue rules, one line shows every agent of the project, in the order CTO, DEV, QA, as the CTO's reports on the agents read: its state, its signature and role, then, while the agent has something in hand, a colon and a link to the issue (#123) or pull request (PR #124) it works on. The agent's own calls set that item: an issue it labels status:in-progress, whether with squad-set-status.sh, by editing the issue or by creating it so, a PR it creates, and a PR it checks out or reviews. Merging or closing the item ends it. So does setting the issue to another state with squad-set-status.sh, or taking its status label off with none put on, as the author does once the issue's PR is merged. A PR the agent created takes with it the issue its body closes (Closes #123), when the board can read that body: given inline, or in a file named by its absolute path. The band then shows the item before it, or the role alone. Reading, commenting and other label edits change nothing. An idle agent shows its role alone, with no colon; its session keeps the item, which shows again once it works. The board shows what each session does, not what GitHub says: it reads nothing from GitHub. Only the CTO's session draws the band; DEV's and QA's sessions publish their state for it and show nothing of it.

───────────────────────────────────────────────────────────────────────────────────────────────────────────────
💤 👷🏼‍♂️CTO (ctx: 96%) │ ⏳ 👨🏼‍💻DEV: #123 │ 👀 👩🏼‍🔬QA: PR #124       agent-squad (v49) → v50 available: /squad-update
───────────────────────────────────────────────────────────────────────────────────────────────────────────────

On the right of the line, the squad's part:

agent-squad and the release of the board the CTO's session loaded;
⏩ before it while the squad is on autopilot, from /squad-autopilot until /squad-resume or /squad-pause;
after it, in the CTO's yellow, → v50 available: /squad-update while a newer release than the installed one is out. /squad-update shows you what it changes, and /squad-upgrade installs it; the board installs nothing. It reads the latest release from .agent-squad/latest-release, a file the squad keeps, and connects to nothing itself.

On a narrow terminal the agents keep the room: the notice shortens to → v50, then goes, then ⏩ goes. Only then is the line cut at its end, after whole agents, with an ellipsis. Narrower still, when the CTO's part and the ellipsis no longer fit beside agent-squad, the line keeps only them.

Each role's name is in the colour Quick start, step 2, gives its session: the CTO yellow, DEV blue and QA green.

The states:

⏳ working;
👀 working, for QA, who reviews;
✋ waiting for you, on a permission or a question, with a notice in the CTO's session;
⚙️ its turn ended with a shell still running in the background, until the shell ends; it reads messages meanwhile, since no turn runs;
⏸️ paused, from /squad-pause until /squad-resume or /squad-autopilot;
💤 idle, free for the next request, with no item;
❓ unknown: no state from that session for three minutes.

The CTO's context shows once it reaches 90% of its window, as (ctx: 96%) right after its role.

The board is a Claude Code mod, which the installer enables for this project alone. It needs Claude Code 2.1.287 or later; with an older one, the squad works without it. It only watches: it never answers a prompt for you, runs no command, and makes no network call, and the one file it writes is each session's record in .agent-squad/sessions/, the release that session loaded, which /squad-resume reads. The latest release, which the board's notice names, is checked by the squad's hooks and scripts instead. A session start always asks GitHub, however recent the last check: a new session, a resumed one, a /restart or a /clear, though not a compaction. So do /squad-update and /squad-upgrade, so that the notice names the release they report. Otherwise they check once a day in a session that stays open, and when the CTO runs /squad-resume or /squad-watch, never twice within a day, nor more than once an hour while GitHub cannot be reached. After an upgrade, restart the three sessions, with /restart in each, to load the new board; until the CTO's session restarts, its line still shows the previous release. Until then, the band marks each session still on another board than the installed one, older, or newer after going back to an older release, with the release it loaded and the one installed, DEV ⟳ v50→v53, and the mark goes once that session restarts; /squad-resume names those sessions too. To turn it off, run the claude plugin disable line the installer printed, in the main checkout; the same line with enable turns it back on.

📋 Requirements

Claude Code, with the three sessions on the same machine; 2.1.287 or later for the squad board, which an older one goes without.
A GitHub repository for your project.
The GitHub CLI, gh, logged in with the repo and workflow scopes.
bash, git 2.31 or later, jq, tar, and sha256sum or shasum, which macOS, Linux and Git Bash already have.
macOS or Linux. The squad is tested on both, and on Linux in CI. Windows with Git Bash is best effort: it is untested in CI.

Before it touches anything, the installer checks that gh, git, jq, tar and a SHA-256 tool are there, and that gh is logged in and can read gzurl/agent-squad. If something is missing, it stops and says what; it does not install anything for you.

🔄 Upgrade

When a new release is out, the squad board says so. To know what it changes first, type /squad-update in the CTO's session: the CTO tells you which release the project runs, what the new one changes and whether you need to do anything, and installs nothing. To install it, type /squad-upgrade in the CTO's session, or /squad-upgrade vN for a given release: typing it is your yes, so the CTO asks nothing more, and you need not run /squad-update first. Before installing, the CTO brings DEV and QA to a safe point, as /squad-pause does, since the install replaces the scripts their hooks and pushes run. If the installer leaves a step undone, or the installation's check fails, the CTO stops there and tells you. The agents then re-read the rules that changed, so the rules need nothing more from you; the CTO asks you to compact the sessions only after a release that rewrites much of the charter. The upgrade also moves the squad board to the new release, and keeps it off if you turned it off, and the CTO creates any label the release adds. Then the CTO asks you to restart the three sessions, with /restart in each, the CTO's last, which keeps each session's conversation and name: until a session restarts, it keeps the board it started with, and a hook the release adds waits for it too, so the CTO's line shows the previous release, with the new one's notice. A session that restarts waits for someone to write to it, so you then type /squad-resume in the CTO's session, and the agents carry on from where they stopped. The CTO ends with the version installed and its release's headlines; the release notes are in CHANGELOG.md.

If /restart refuses with this session belongs to <directory> but is running in <checkout>, the session was started or resumed from another directory, a subdirectory included. Its memory is not the squad's, and the squad's hooks say so at its start. Exit it and start a new session from the main checkout, without --resume.

To remove the squad from a project, type /squad-uninstall in the CTO's session. The CTO shows you what would go and what would stay. When you say yes, it first merges a PR for what git tracks, then removes the rest. With no squad session open, run .agent-squad/playbook/scripts/squad-uninstall.sh . from the project's main checkout, with --dry-run first to see what it would do.

What it removes: what the installer wrote outside git. That is the hooks, the exclusion of the worktrees' instructions, the commands, the pre-push shim (your own pre-push goes back in place), the ssh keepalive in .git/config, the board's mods, the worktrees and .agent-squad/.
What it keeps: the squad's records (compaction snapshots, review evidence, token history), and what a worktree held that git ignores, such as a .env, which it moves into .agent-squad/kept/. --records removes them too.
When it stops: while a worktree holds work that is not committed or not pushed, it removes nothing.
What it leaves: a list of the tracked files the squad added, for the CTO to remove through a PR.

Removing .agent-squad/ by hand instead leaves the hooks behind in .claude/settings.local.json, failing at every session start.

🗂️ What goes where

The installer of Quick start can run as often as you like: it prints every step, and never overwrites or deletes a file your project owns. It installs the latest release. To install into another folder, add it after bash -s --, and to pin a release, add --tag vN with one of the tags:

curl -fsSL https://raw.githubusercontent.com/gzurl/agent-squad/main/install.sh \
  | bash -s -- /path/to/project

Everything the squad installs or generates lives in .agent-squad/, which git ignores. Outside it, the installer touches only the files listed before it:

<project>/
├── AGENTS.md, CLAUDE.md → AGENTS.md      in git    your conventions, and the charter's import
├── .agent-squad-checks                   in git    the checks the pre-push gate runs
├── .gitignore                            in git    ignores .agent-squad/, the local settings, the commands
├── .github/                              in git    issue and PR templates, only if you had none
├── .claude/settings.local.json           ignored   the squad's hooks, its board, and the worktrees' instructions
│                                                   left out, next to your settings
├── .claude/commands/squad-*.md           ignored   the squad's commands
├── .git/hooks/pre-push                   in .git   runs the pre-push gate, after any hook you had
├── .git/config                           in .git   core.sshCommand, an ssh keepalive, so that a push
│                                                   outlasts long checks, unless you set your own
└── .agent-squad/                         ignored
    ├── playbook/          the installed release: charter, scripts, templates, mods
    ├── .claude-plugin/    the project's marketplace for the squad's mods, which are playbook/mods/
    ├── worktrees/         dev/ and qa/, plus one cto-<topic>/ per pull request of the CTO
    ├── handoff/           the snapshot saved before each compaction
    ├── evidence/          the files QA's reviews rely on
    ├── install.log        one line per install or upgrade
    ├── tokens.tsv         the history of the tokens each agent used, kept by /squad-usage
    ├── watch.tsv          what /squad-watch has reported, so that each stall is reported once
    ├── triage.since       when the CTO last triaged what came from outside
    ├── kept/              what the worktrees held that git ignores, kept by the uninstaller
    ├── squad-hook         the small wrapper the squad's hooks run
    ├── latest-release     the latest release, for the board's notice
    ├── sessions/          the release each session's board loaded, for /squad-resume
    └── playbook.manifest  the checksums that --check compares the playbook against

An upgrade replaces playbook/, only once the new one is complete, and rewrites the hooks, the exclusion of the worktrees' instructions, the pre-push hook, playbook.manifest and the mods' marketplace, which keeps its name. It removes from .claude/commands/ any squad-*.md the new release no longer has, as after a command is renamed, unless your project tracks that file. It leaves the rest alone. SQUAD.md §2.4 says who cleans up what, and when.

To check the installation at any time, run .agent-squad/playbook/scripts/squad-install.sh --check . in the main checkout. It changes nothing: it prints check: ok or check: FAILED with the reason for each item, and proves that the pre-push gate refuses a failing check. Until the CTO has finished BOOTSTRAP.md, the items it leaves to the CTO fail.

Never run git clean -d with -x or -X in the main checkout. It deletes what git ignores there: the playbook, the snapshots, the evidence and .claude/settings.local.json, and with -ff the worktrees too.

⌨️ Commands

You type them in a Claude Code session of the squad. Each -all variant does the same for every squad on the machine.

The commands that pause, steer, resume, update, upgrade or remove the squad, and /squad-save-state, are yours alone: no agent can run one on its own. When the CTO passes one on to DEV and QA, they read its file and follow their part, which still works. /squad-watch and /squad-usage the agents may run themselves, as autopilot does with the watch.

Command	Type it in	What it does
⏸️ `/squad-pause` `/squad-pause-all`	the CTO's session	Stops the squad at a safe point, each agent's state saved on GitHub (When you step away).
⏩ `/squad-autopilot` `/squad-autopilot-all`	the CTO's session	You leave, the machine stays on: the squad carries on and leaves your decisions on GitHub.
▶️ `/squad-resume` `/squad-resume-all`	the CTO's session	You are back: what was done, what waits for you, and the plan ahead.
🔎 `/squad-watch`	the CTO's session	Looks for stalled work and pings whoever owns its next step; autopilot runs it every half hour.
💾 `/squad-save-state`	any session	Its agent writes its state on GitHub, before you type `/compact` (When a session's context fills up).
📊 `/squad-usage` `/squad-usage-all`	any session	The tokens each agent has used (How many tokens the agents use).
🔔 `/squad-update`	the CTO's session	What a newer release changes; installs nothing (Upgrade).
🔄 `/squad-upgrade` `/squad-upgrade vN`	the CTO's session	Installs the latest release, or vN, with no question: typing it is your yes (Upgrade).
🧹 `/squad-uninstall`	the CTO's session	What removing the squad would do; on your yes, a PR for the tracked files, then the rest goes (Upgrade).

❓ FAQ

Why three agents, and not one? One agent checks its own work with the same context it wrote it in. A second one, with a fresh context, checks it honestly, and a CTO settles their disagreements so that you are not dragged into them.

How many tokens does it use? Three Claude Code sessions per project. /squad-usage shows each agent's tokens; most of the input is read from the cache, which costs far less.

Does it work with Codex, Cursor or other tools? Not today. agent-squad relies on these Claude Code features, and another tool would need an equivalent of each:

sessions that message each other, and a list of the sessions open on the machine, with whether each is busy, idle or waiting;
named sessions, so that each agent knows its role;
hooks that run before a compaction and when a session starts or resumes;
custom slash commands (.claude/commands/);
a memory shared by the sessions launched from the same folder;
compaction that follows the project's instructions on what to keep;
session transcripts kept on the machine, which /squad-usage reads;
/loop, which runs a command again on a schedule, as the CTO runs /squad-watch every half hour while you are away;
mods, for the squad board, which the squad can do without.

It also relies on GitHub, through the gh command line.

Do I have to watch three terminals? No: you talk only to the CTO. The others work on their own and report through it, and the CTO tells you when one of them is waiting for you in its own terminal, for a permission or a question.

Can I use it on an existing project? Yes. The CTO starts by studying the codebase and asking you what it needs to know.

Can I ship a fix to a release that is already out? Yes, from a release branch such as release/1.2, while main carries the next release. List the pattern of your release branches in .agent-squad-release-branches, at the project's root, and the squad holds those branches as it holds main: only a PR that QA reviews changes them, and the pre-push gate refuses a direct push. The fix goes to main first, and a backport carries it to the release branch. To cut a release branch from its tag, check the tag out and push it as the new branch, git push origin HEAD:refs/heads/release/1.2: a push that creates a release branch at a commit that the remote's default branch, a release branch or a tag already holds needs no exception and runs no check. A commit that only a feature branch holds needs a PR first.

Can the checks before a push run side by side? Yes, when they keep out of each other's way: no port, database or fixed file that two of them use. Add the line # squad-checks: side by side to .agent-squad-checks, and the pre-push gate starts them all at once. Each still gets its status line, the output of one that fails is shown once it ends, and the push is refused when any fails. A check run so must not read the terminal, which would stop it. Without that line they run one after another, and so they do under a release that does not know it, which reads it as a comment.

Does it collect anything about me? No. Nothing in agent-squad calls home, and nothing about you or your project is sent anywhere. Each release is published as a GitHub Release with its package attached, which the installer downloads and checks against the SHA-256 GitHub publishes for it. GitHub counts each package's downloads, one number per version, which the downloads badge above adds up, and that number is all the squad sees: nothing about who downloaded it, or from where.

What comes next? Whatever the open issues say, with no date promised. Ideas are welcome as issues (CONTRIBUTING.md).

🤝 Contributing

To report a problem or propose an idea, open an issue: CONTRIBUTING.md says how. The squad turns accepted issues into its own pull requests. Your issue then shows the squad issue that answers it, as the issue that blocks it.

CONTRIBUTING.md also lists what each file of this repository is, and which ones a release ships.

📄 License

agent-squad is released under the MIT License: use it, change it and share it freely, keeping the copyright notice and the license text with it. If it shapes how your team works, a link back is appreciated.