Agent Team — Claude Code Plugin

Run a full AI engineering team on your codebase. Instead of asking one AI to do everything, you define roles (Frontend Engineer, Backend Engineer, QA, etc.), assign each a model, and deploy them all at once. They work in parallel, talk to each other, and Claude coordinates the whole session.

---

Install

The plugin is not on the official marketplace yet. Install it directly from GitHub:

# 1. Add the plugin repo as a source (one time only)
claude plugin marketplace add https://github.com/usmanNoor5/plugins.git

# 2. Install the plugin
claude plugin install agent-team

Restart Claude Code after installing. To verify it worked:

claude plugin list

You should see agent-team in the output.

---

When to use it

Use agent-team when a task is too large or too cross-cutting for a single AI session:

Building a full feature that touches frontend, backend, and database at the same time
Greenfield projects where you need multiple layers built simultaneously
Refactors that span many files or modules where different parts can be worked on independently
Adding tests while development is still happening in parallel
Any task where you'd normally context-switch between multiple concerns

Not useful for: small single-file changes, quick fixes, or anything one model can handle in one go.

---

Setup (once per project)

Run the setup wizard. It detects which AI providers you have installed and walks you through defining your team:

/agent-team:setup

It will ask you: 1. What roles do you need? (e.g. Frontend Engineer, Backend Engineer, QA) 2. Which model powers each role? (Codex, Gemini, OpenCode, or Claude) 3. Which folders should each agent see?

At the end it writes a team.json to your project root. You only do this once per project.

Supported models

| Model | What you need | |---|---| | OpenAI Codex | npm install -g @openai/codex then codex login | | Google Gemini | npm install -g @google/gemini-cli then gemini auth login | | OpenCode | curl -fsSL https://opencode.ai/install \| bash | | Claude | Already available — no setup needed |

Check all your providers are ready before starting:

/agent-team:agents

---

Prepare your project docs (important)

Agents only know what you show them. Before running a session, you need a planning/PLAN.md file at your project root that fully describes the project. This is the single most important thing you can do to get good results — agents read this first every round.

What to put in PLAN.md

Your PLAN.md should answer these questions for every agent:

1. What is this project? A short description of what you're building, who it's for, and what it should feel like. Not a sentence — a paragraph. Agents use this to make judgment calls.

2. What does the user experience look like? Describe the UI flows, what the user sees on first load, what they can do, and how it should feel. Frontend agents use this to make layout and interaction decisions without asking.

3. Architecture decisions Which stack, why, and where the boundaries are. What does the frontend talk to? What does the backend own? Where does the database live? Agents will follow what they read here, so if you care about a decision, document it.

4. Directory structure Show the full tree with a one-line description of each folder. Agents use this to know where to write files without guessing.

5. What is already built vs what is still to do Agents will waste a round re-doing completed work if you don't tell them it's done. Be explicit.

Example structure

planning/
├── PLAN.md              ← main document, agents read this every round
├── API.md               ← endpoint contracts (backend ↔ frontend)
├── SCHEMA.md            ← database schema
└── MARKET_DATA.md       ← notes on a completed component

Minimal PLAN.md template

# Project Name

## What This Is
[2-3 sentences describing the project and its purpose]

## User Experience
[What the user sees on first load, what they can do, visual style]

## Architecture
[Stack choices and why — frontend framework, backend language, database, etc.]

## Directory Structure
[Tree with one-line descriptions of each folder]

## What's Done
- [component or feature]: [brief status]

## What Still Needs Building
- [component or feature]: [what's needed]

## Key Constraints
[Anything agents must not change — API contracts, naming conventions, etc.]

The more detail the better

Agents read the first 50 lines of PLAN.md automatically every round. If your key decisions are buried on page 3, agents may not see them. Put the most important constraints — stack choices, file locations, boundaries between roles — near the top.

If a component is fully done, say so explicitly. If an API contract is fixed, write it down. Agents will not step outside what you've documented.

---

Run your team

/agent-team:start "Build the user authentication module with login, signup, and JWT"

Every agent fires at the same time. Claude reads each result, routes messages between agents, and runs more rounds if needed until the task is done.

To watch agents work live in your terminal (requires tmux):

/agent-team:start --tmux "Build the user authentication module"

This opens a tiled terminal with one pane per agent. Attach with:

tmux attach -t agent-team-<session-id>

---

Commands

Managing your session

| Command | What it does | |---|---| | /agent-team:setup | Interactive wizard to create your team | | /agent-team:start "<task>" | Deploy all agents on a task | | /agent-team:start --tmux "<task>" | Same, but open a live tmux view | | /agent-team:session | Check which agents are working, done, or waiting | | /agent-team:agents | See every agent, their model, and auth status | | /agent-team:message <agent-id> "<text>" | Send a mid-session message to a specific agent | | /agent-team:recall | Browse memory from past sessions | | /agent-team:recall <keyword> | Search past sessions by topic |

Sending messages to agents mid-task

If you want to redirect an agent while a session is running:

/agent-team:message backend-engineer "Use PostgreSQL instead of SQLite"
/agent-team:message frontend-engineer "The API now returns camelCase — update your types"
/agent-team:message all "Stop — requirements changed, wait for my next message"

The agent gets your message at the start of their next round.

Checking and changing models

Each provider has three commands:

/agent-team:codex-login       /agent-team:codex-status       /agent-team:codex-model
/agent-team:opencode-login    /agent-team:opencode-status    /agent-team:opencode-model
/agent-team:gemini-login      /agent-team:gemini-status      /agent-team:gemini-model

login — check if you're authenticated
status — see version, auth method, current model
model — switch which model variant a role uses (no args = interactive picker, with args = instant write)

Example — switch all Codex roles to a faster model:

/agent-team:codex-model gpt-5.4-mini all

Example — change just one role:

/agent-team:opencode-model github-copilot/gpt-4.1 backend-engineer

Model choices are saved to team.local.json (gitignored) so they don't affect your teammates' setup.

---

How agents remember things

Within a session — each agent builds up results round by round. OpenCode agents resume the same session natively. Codex and Gemini agents get their previous round outputs prepended to each new prompt, so they always know what they already did.

Across sessions — after every session finishes, a summary is saved to ~/.agent-team/memory/. On future sessions with similar tasks, the top matching memories are injected into each agent's prompt automatically. Agents learn from past work without you doing anything.

Between agents — agents talk to each other mid-task using this format in their responses:

MESSAGE TO backend-engineer: I need /api/prices to return a 24h high/low field.
MESSAGE TO coordinator: Done. I created 3 new components in frontend/components/.

Claude routes these automatically. Each agent reads their teammate messages at the start of the next round.

---

If a model runs out of quota

The plugin handles this automatically. If an agent hits a rate limit, it switches to the next available model in the chain and keeps going — no manual intervention needed, same round continues.

| Primary | Automatic fallback | |---|---| | Gemini | → OpenCode → Codex | | OpenCode | → Codex | | Codex | → OpenCode |

---

Troubleshooting

"No team.json found" — run /agent-team:setup first.

Agent fails immediately — run the login command for that provider to check auth.

Gemini model not found — use gemini-3-flash-preview (not gemini-3-flash). The -preview suffix is required.

OpenCode model not found — model IDs must be lowercase: github-copilot/gpt-5.3-codex not GPT-5.3-codex.

Want to read what an agent produced? Results are plain markdown files:

cat ~/.agent-team/sessions/<session-id>/agents/<role>/results/1-result.md

agent-team

Summary

Install to Claude Code