amq-squad

amq-squad

Role-aware agent team launcher built on top of AMQ by Aviv Sinai.

AMQ owns messaging between agents. amq-squad owns the layer above: who is on the team, what role each agent plays, what shared norms they follow, and how to bring the whole squad up, down, back, or into a new workstream.

Why

AMQ's coop exec is a generic launcher. It sets up a mailbox and execs into claude or codex, but it does not know:

• Which agent is the "CTO" vs "Fullstack" vs "QA" vs "PM" vs "Designer"
• What command originally launched each one (cwd, binary, flags, workstream)
• What durable team norms each agent should read at session start
• Which peers a given agent actively talks to

amq-squad captures this at team-setup time (.amq-squad/team.json, .amq-squad/team-rules.md) and per-agent at launch time (launch.json + role.md inside the AMQ mailbox). AMQ itself stays unchanged.

Install

Install the 1.5 line:

go install github.com/omriariav/amq-squad/cmd/[email protected]
amq-squad version

For the latest 1.x build:

go install github.com/omriariav/amq-squad/cmd/amq-squad@latest

Requires Go 1.25+, the amq binary on PATH (v0.34+), and tmux on PATH for amq-squad up.

Skills (plugin marketplaces)

This repo doubles as a plugin marketplace that ships the amq-squad skills (amq-squad, amq-team-setup, amq-squad-role-creator) for both Claude Code and Codex. The CLI and the skills are versioned together.

Claude Code:

/plugin marketplace add omriariav/amq-squad
/plugin install amq-squad@amq-squad

Codex:

codex plugin marketplace add omriariav/amq-squad
codex plugin add amq-squad@amq-squad

The Claude marketplace manifest lives at .claude-plugin/marketplace.json and the Codex one at .agents/plugins/marketplace.json; each points at the binary-specific plugin under plugins/claude and plugins/codex. In Claude Code, skills are namespaced by plugin, e.g. /amq-squad:amq-squad-role-creator. In Codex, invoke them by skill name, e.g. $amq-squad-role-creator.

Quick start

cd ~/Code/my-project

amq-squad roles                      # list role IDs and market numbers
amq-squad new team --dry-run --roles cto,qa
amq-squad new team --dry-run --json --roles cto,qa
amq-squad new team --sync --session issue-96
amq-squad new profile review --roles cto,qa --sync --session review

amq-squad up --dry-run               # preview the launch plan
amq-squad up --project ~/Code/other-app --dry-run
amq-squad new session issue-96       # NEW work: bring the team up live in tmux
amq-squad new session issue-98 --seed-from issue:31
amq-squad new session --project ~/Code/other-app issue-97

amq-squad                            # bare command -> multi-session status board
amq-squad status --session issue-96  # single-session detail
amq-squad status --project ~/Code/other-app --session issue-97
amq-squad console                    # live read-only Mission Control TUI
amq-squad console --project ~/Code/other-app --once
amq-squad doctor                     # AMQ version / tmux / wake / pointer sync
amq-squad doctor --project ~/Code/other-app --profile release
amq-squad doctor --project ~/Code/other-app --all-profiles
amq-squad amq env --session issue-96 # resolved AMQ root/session/handle
amq-squad amq ops --session issue-96 # AMQ operational diagnostics
amq-squad amq route --session issue-96 --me cto --to fullstack

amq-squad stop --all                 # SIGTERM the team (--force = SIGKILL); stays resumable
amq-squad stop --project ~/Code/other-app --all --session issue-97
amq-squad resume                     # re-orient / reattach the saved session
amq-squad resume --project ~/Code/other-app --session issue-97
amq-squad fork --from issue-96 --as issue-96-review  # branch a fresh workstream
amq-squad fork --project ~/Code/other-app --from issue-96 --as issue-96-review
amq-squad rm issue-96                # remove a finished session (confirm-gated; or `archive`)

The 1.3 lifecycle

A session moves through one small state machine:

(none) --up--> running --stop--> stopped --rm/archive--> (none)
                  ^                  |
                  +------ resume ----+