agent-team
Manages AI team roles using git worktrees + terminal multiplexer tabs. Each role runs in its own isolated worktree (branch
) and opens as a full-permission AI session in a new tab.
For directory layout and bidirectional communication details, see references/details.md.
Install
bash
brew tap JsonLee12138/agent-team && brew install agent-team
Upgrade
bash
brew update && brew upgrade agent-team
Usage
Run from within a project git repository:
Use tmux backend (default is WezTerm):
bash
AGENT_TEAM_BACKEND=tmux agent-team <command>
Brainstorming (Required Before Assign)
When the user intends to assign new work to a role, you MUST brainstorm first:
- Explore context — check the role's , existing , and project state
- Ask clarifying questions — one at a time, prefer multiple choice when possible
- Propose 2-3 approaches — with trade-offs and your recommendation
- User confirms design — get explicit approval
- Write proposal — save the confirmed design to a temp file
- Execute assign — run
agent-team assign <name> "<desc>" --proposal <file>
Rules:
- Brainstorming is mandatory for new work assignments
- Can be skipped when user explicitly says "just assign" or provides a complete design
- One question at a time. YAGNI. Explore alternatives before settling.
Commands
Create a role
Creates
git branch + worktree at
. Generates:
agents/teams/<name>/config.yaml
agents/teams/<name>/prompt.md
- — OpenSpec project structure for change management
After creating, guide the user to edit
to define the role's expertise and behavior.
Open a role session
bash
agent-team open <name> [claude|codex|opencode] [--model <model>]
- Generates in worktree root from (auto-injected as system context)
- Spawns a new terminal tab titled running the chosen AI provider
- Provider priority: CLI argument >
config.yaml default_provider
- Model priority: flag >
config.yaml default_model
Open all sessions
bash
agent-team open-all [claude|codex|opencode] [--model <model>]
Opens every role that has a config.yaml.
Assign a change
bash
agent-team assign <name> "<description>" [claude|codex|opencode] [--model <model>] [--proposal <file>]
- Creates an OpenSpec change at
openspec/changes/<timestamp>-<slug>/
- Writes the proposal file from flag (or empty if not provided)
- Auto-opens the role session if not running
- Sends a notification to the running session
The role will then use
to proceed through specs → design → tasks → apply.
Reply to a role
bash
agent-team reply <name> "<answer>"
Sends a reply to a role's running session, prefixed with
.
Reply to main controller (used by roles)
bash
agent-team reply-main "<message>"
Sends a message from the role back to the main controller's session, prefixed with
. Automatically detects the current role from the worktree directory and reads the controller's pane ID from
.
Check status
Shows all roles, session status (running/stopped), and active OpenSpec changes.
Merge completed work
Merges
into the current branch with
. Run
afterward to clean up.
Delete a role
Closes the running session (if any), removes the worktree, and deletes the
branch.