A universal agent orchestrator for Claude Code, Codex, and Cursor.
Nine characters from Avatar: The Last Airbender. 58 engineering skills. One mode that routes the work.
Created by ZeroClickDev
team-avatar-demo-readme-720p.mp4
App screens are recreated from this repository's real runs and files. Narration is an AI clone of the author's voice.
Claude Code:
claude plugin marketplace add tmcfarlane/team-avatar && claude plugin install team-avatar@team-avatarCodex:
codex plugin marketplace add tmcfarlane/team-avatar && codex plugin add team-avatar@team-avatarCodex starts character subagents only when multi_agent = true is set under [features] in ~/.codex/config.toml.
Then ask for avatar-mode (/team-avatar:avatar-mode in Claude Code, $avatar-mode in Codex) with any engineering task. plugins/team-avatar has the full roster and every skill.
Each character runs on the model named in your model sheet, and avatar-setup writes that sheet. On Codex, run $avatar-setup once. The built-in defaults name Claude models, which Codex can't run. Pick the models lists the defaults.
Open a repository and ask Team Avatar to explain its structure and test setup. This first task is read-only.
Claude Code:
/team-avatar:avatar-mode Explain this repository's structure and how to run its tests. Cite the relevant files. Do not change any files.
Codex:
$avatar-mode Explain this repository's structure and how to run its tests. Cite the relevant files. Do not change any files.
Team Avatar started in Cursor as oh-my-cursor. I upgraded to Cursor Ultra with 9 days left to burn about $300 in tokens, and built agent swarms to do real work while responsibly (irresponsibly) optimizing token burn. Turns out all it takes is Markdown config files and one orchestration rule. That edition still ships, and Team Avatar for Cursor covers it.
We took pstack, Lauren Tan's excellent agent workflow pack, by way of Michael Denyer's Claude Code and Codex port. Then we slapped Avatar characters on top of it.
It probably made it worse. It is definitely cooler.
Every pstack skill and playbook is here, renamed and owned by a character. Katara heals bugs. Toph reviews your diff and does not care about your feelings. Zuko owns performance and incidents. Iroh writes the docs and makes the tea. Aang routes everything through avatar-mode. NOTICE credits every upstream source.
We measured it, too. On SWE-bench Verified Mini, Team Avatar, pstack, and no plugin at all solve about the same number of tasks in both Claude Code and Codex. None of the gaps is statistically significant, and both plugins cost more per task. You are not buying a higher score. You are buying habits: reproduce the bug first, write the regression test, review the diff, explain the number.
Each app gets one short request. The prompt names avatar-mode and three bug reports, and avatar-mode picks the workflow and the characters. These are unedited window captures from Claude Desktop and the Codex app. An agent typed each prompt by driving the app. How they were made.
/team-avatar:avatar-mode Fix these three reported issues: the cart total comes out a cent short, slugs still have spaces in them, and page 1 shows the second page of results.
Claude Desktop. Avatar-mode answers with its own plan. The first step loads healing-water, Katara's bug workflow.
It fixes each bug against its failing test, then runs two Toph reviews at the same time in the Background tasks pane. It skips the pull request because the demo repo has no remote.
The reply explains each root cause with what it measured. It made one branch per bug, and with all three applied, 6 of 6 tests pass.
Codex. Type $avatar-m and the picker lists Team Avatar's skills.
From the same request, avatar-mode sends Toph to investigate and Katara to fix, then starts a Toph correctness review and a Toph quality review. This frame shows the two reviews running. Codex lists Katara on the same line, but Katara had already finished.
The finished activity log shows the investigation, the fix, and the two reviews. All three tests pass.
Every skill is a plain Markdown SKILL.md in the Agent Skills format, so any coding harness that loads Agent Skills can run them, including OpenCode, Hermes Agent, OpenClaw, Muse Code, Gemini CLI, GitHub Copilot, Amp, and Goose. T3 Code runs the Claude Code, Codex, Cursor, and OpenCode agents already on your machine, so install Team Avatar into the one it drives.
The skills CLI installs the 58 skills for the agents you pick:
npx skills add tmcfarlane/team-avatar/plugins/team-avatarKeep the plugins/team-avatar path. The repository root also holds the Cursor edition's skills, and a bare tmcfarlane/team-avatar lists both sets.
To install by hand, copy each folder in plugins/team-avatar/skills/ into a directory your harness scans. OpenCode, OpenClaw, and Muse Code all read ~/.agents/skills/. Hermes Agent reads ~/.hermes/skills/, or add ~/.agents/skills to skills.external_dirs in ~/.hermes/config.yaml.
Outside Claude Code and Codex you get the skills on their own. The team-avatar:<character> subagents, the session hook, and the helper tools that master-plan, kyoshi-command, long-flight, and safe-landing run from plugins/team-avatar/tools come only with the plugins.
The Cursor edition still ships as config files: 8 agents, 9 slash commands, hooks that block bad commits, and one orchestration rule. It runs on Cursor's built-in Task subagents, with no external runtime and no wrapper CLI. It doesn't use the plugin above.
Each agent runs on its own model through Cursor's model: field. An invalid model slug falls back to the default without an error, so every slug here is verified against a real Cursor build (VALIDATION.md).
Jump to: Install · Orchestrator · Agents · Model policy · Slash commands · Orchestration modes · Architecture · Hooks · Automations · Bundled skills · FAQ
You need Cursor 3.4 or later with agent mode (subagents). Nothing else.
macOS and Linux:
curl -fsSL https://raw.githubusercontent.com/tmcfarlane/team-avatar/main/install.sh | bashWindows (PowerShell):
irm https://raw.githubusercontent.com/tmcfarlane/team-avatar/main/install.ps1 | iexInstaller options
Append a flag to the macOS and Linux one-liner above. To work from a checkout, clone the repository and run bash install.sh with the same flags.
bash -s -- --project # Install to this project only (./.cursor/)
bash -s -- --claude --codex # Also copy the Cursor edition into .claude/ and .codex/
bash -s -- --no-skills # Skip the bundled skills
bash -s -- --dry-run # Preview changes
bash -s -- --force # Update or overwrite existing files
bash -s -- --uninstall # Uninstall
bash -s -- --disable # Disable orchestration (agents stay)
bash -s -- --enable # Re-enable orchestration--claude and --codex copy the Cursor edition's agents, rules, commands, and hooks. For the Claude Code and Codex plugin, use Install instead.
On Windows:
# PowerShell 7+ / Windows 11 one-liner with flags:
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/tmcfarlane/team-avatar/main/install.ps1))) -Scope project -Force
# Or clone and run locally (all versions):
git clone https://github.com/tmcfarlane/team-avatar.git && cd team-avatar
.\install.ps1 # Default (user scope)
.\install.ps1 -Scope project # Project scope
.\install.ps1 -AlsoClaude -AlsoCodex # Also copy the Cursor edition into .claude/ and .codex/
.\install.ps1 -NoSkills # Skip the bundled skills
.\install.ps1 -Force # Overwrite
.\install.ps1 -Uninstall # RemoveWindows PowerShell 5.1 runs irm | iex with the defaults only. To pass flags there, clone the repository.
The installer writes to these folders:
| Scope | Agents | Rules | Commands | Hooks | Skills |
|---|---|---|---|---|---|
--user (default) |
~/.cursor/agents/ |
~/.cursor/rules/ |
~/.cursor/commands/ |
~/.cursor/hooks/ |
~/.cursor/skills/ |
--project |
./.cursor/agents/ |
./.cursor/rules/ |
./.cursor/commands/ |
./.cursor/hooks/ |
./.cursor/skills/ |
--claude |
Also .claude/agents/ |
Also .claude/rules/ |
Also .claude/commands/ |
Also .claude/hooks/ |
Not copied |
--codex |
Also .codex/agents/ |
Also .codex/rules/ |
Also .codex/commands/ |
Also .codex/hooks/ |
Not copied |
--no-skills |
✓ | ✓ | ✓ | ✓ | Skipped |
The first time it runs, Cursor may ask you to approve the orchestrator rule. Open ~/.cursor/rules/orchestrator.mdc and click Always Allow.
When you upgrade from v0.1, the installer removes the old agent files, such as hephaestus, prometheus, and atlas.
The orchestrator rule (orchestrator.mdc) turns the root thread into a pure dispatcher. Its only permitted tools are Task, TodoWrite, AskQuestion, and SwitchMode, so all work goes through the specialist agents.
Here is a real example of the root thread's reasoning:
Planning Installation Instructions
I need to follow the orchestrator's guidance, since the root can't use Read directly and must delegate via Task. I have to document this in the README and use iroh, but I'm unsure about the new installation instructions, which might be documented elsewhere. It's critical to know these details, so I could search the repository with iroh/toph for existing install docs. I'll have to organize a plan: dispatch toph to find the installation instructions and have iroh update the README after. Plus, I'll create a to-do list to keep track of everything.
Every sentence maps to an orchestrator rule: agent routing (Iroh for docs, Toph for search), phase chaining (explore, then write), and mandatory task tracking with TodoWrite.
Eight agents, each an Avatar character with its own model and role. Expand an agent to see its skills and a screenshot of it at work.
Aang · The Avatar · composer-2.5-fast
Deep multi-file executor and architecture consultant. Masters all elements.
Master of all four elements. Multi-agent orchestration in action.
Skills: design-patterns-implementation · refactoring-patterns · vercel-react-best-practices
Sokka · The Strategist · claude-opus-4-8-thinking-high
Planning, ambiguity analysis, and plan review. The brain behind every mission.
Ask first, dispatch second. The orchestrator clarifies before it sends agents.
Skills: architect · planning · technical-roadmap-planning
Katara · The Healer · composer-2.5-fast
Disciplined implementation, debugging, and methodical fixes. Mends broken code.
Precision healer. Surgical debugging and the smallest possible fix.
Skills: debugging · refactoring · refactoring-patterns
Zuko · The Firebender · gemini-3.1-pro
Visual design: image generation, icons, and UI mockups. Brings designs to life.
Fire and finesse. Image generation, icons, and UI mockups.
Skills: create-an-asset · implementing-figma-designs · web-design-guidelines
Toph · The Seer · composer-2.5-fast
Codebase search, external docs, and media analysis. Sees everything.
Seismic sense. Multi-angle codebase search and doc exploration.
Skills: codebase-search · exploring-codebases · mgrep-code-search
Appa · The Heavy Lifter · composer-2.5-fast
Systematic task list execution. Carries the team.
Plan executor. Works through the task list one step at a time.
Skills: frontend-builder · vercel-composition-patterns · vercel-react-best-practices
Momo · The Scout · composer-2.5-fast
Quick, focused tasks. Small, agile, and independent.
Speed demon. Parallel micro-tasks at maximum speed.
Skills: refactoring · refactoring-patterns · vercel-react-best-practices
Iroh · The Storyteller · claude-opus-4-8-thinking-high
Documentation specialist. The only agent that owns the README, the CHANGELOG, and the project docs.
Man of his letters. Iroh spends much of his time writing letters to family.
Skills: crafting-effective-readmes · docs-write · documentation-engineer · documentation-writing
Every agent defaults to Composer 2.5 (composer-2.5-fast), which is fast and draws on Cursor's Auto and Composer pool (#20, #21). Cursor's model docs list what is currently available. Three agents use a different model:
| Agent | Model | Reason |
|---|---|---|
| Sokka | claude-opus-4-8-thinking-high |
Maximum reasoning for complex planning |
| Iroh | claude-opus-4-8-thinking-high |
Long-form documentation quality |
| Zuko | gemini-3.1-pro |
Multimodal and visual work |
Workers that a coordinator spawns may use Cursor's fast tier or inherit the coordinator's model. If a workflow regresses on Composer 2.5, change model: in the agent's Markdown file.
Cursor's model: field in an agent's frontmatter routes that agent to a specific model (Cursor docs). The value must be an exact, valid Cursor Task tool slug. Cursor does not accept alias strings there:
---
model: composer-2.5-fast # fast executor pool
------
model: gemini-3.1-pro # multimodal tasks
---An unrecognized slug does not error. It falls back to
composer-2.5-fastwithout telling you. A typo or a stale name looks like it works while the agent runs the wrong model. Use a verified slug and confirm the routing withVALIDATION.md. An agent with nomodel:line inherits its parent's model.
Valid slugs on Cursor 3.8.x, verified in June 2026: composer-2.5-fast, claude-opus-4-8-thinking-high, gemini-3.1-pro, claude-4.6-opus-high-thinking, claude-4.6-sonnet-medium-thinking, claude-fable-5-thinking-high, gpt-5.3-codex-high-fast, gpt-5.5-medium, and kimi-k2.5.
Slugs change between Cursor versions, and Cursor's docs don't mention it. Verify them against your build before you rely on routing. The VALIDATION.md sweep takes about 2 minutes.
Type a command in Cursor's chat to run its workflow:
| Command | Agent | Purpose |
|---|---|---|
/plan |
Sokka | Full planning pipeline: ambiguity analysis, plan creation, and self-review |
/build |
Aang | Deep multi-file implementation with verification |
/search |
Toph | Multi-angle exploration of the codebase and docs |
/fix |
Katara | Methodical debugging and code healing |
/tasks |
Appa | Systematic task list execution |
/scout |
Momo | Quick, focused tasks |
/doc |
Iroh | Documentation generation and updates |
/image |
Zuko | Cursor image generation (Nano Banana Pro) for icons, mockups, and prompts |
/cactus-juice |
Swarm | Splits the request into micro-tasks and spawns up to 10 parallel workers |
Cursor's agent generates images with Google Nano Banana Pro and saves previews under assets/ by default. Team Avatar routes image work to Zuko. His cursor-image-generation skill rewrites a short request into a full prompt, then iterates on the result. Use /image, or delegate with Task(zuko), for image-only work.
Coordinated, tiered orchestration. The orchestrator reads each request and picks which agents to dispatch.
/cactus-juice trades depth for parallelism:
- The root splits your request into 5 to 10 independent micro-tasks, each scoped to a single file.
- Up to 10 subagents start at once with
model: fast. - Each worker writes code with low cognitive complexity.
- The root collects the results, checks that they are consistent, and fixes integration issues.
flowchart TD
U["You (root thread)"] --> R["orchestrator.mdc<br/>(Team Avatar)"]
R --> IG{"Intent gate<br/>what did the user ask?"}
IG -->|"search / 'how does X work?'"| T["Task(toph)<br/>Seer"]
IG -->|"ambiguous / complex scope"| S["Task(sokka)<br/>Strategist"]
IG -->|"visual assets"| Z["Task(zuko)<br/>Firebender"]
IG -->|"complex feature"| PLAN["Task(sokka) → plan"]
PLAN --> IMPL["Task(aang / katara)<br/>Coordinators"]
IMPL -->|"spawns"| T2["toph (fast)"]
IMPL -->|"spawns"| M2["momo (fast / inherited)"]
IG -->|"task list"| AP["Task(appa)<br/>Heavy Lifter"]
AP -->|"spawns"| M3["momo"]
IG -->|"quick task"| MO["Task(momo)<br/>Scout"]
IMPL --> V{"Verification<br/>lints / build / tests"}
V -->|pass| DONE["Done"]
V -->|fail| FR["Failure recovery<br/>(retry → aang → user)"]
subgraph swarmNote ["Swarm Mode (Cursor 3.4+)"]
N1["Coordinators spawn workers async.<br/>Max depth = 2. Workers are leaf nodes."]
end
On Cursor 3.4 and later, the agents run as a two-tier swarm. Coordinators (Aang, Sokka, Katara, and Appa) spawn workers (Toph and Momo) as leaf nodes. Zuko runs only from the root.
| Pattern | How it works |
|---|---|
| Research-then-Act | Spawn Toph for parallel research, collect the results, then implement |
| Fire-and-Collect | Spawn several Momo workers, wait for all of them, and verify each |
Hooks enforce rules at the system level, so nothing depends on an agent remembering to verify. They run through Cursor's hooks system and .cursor/hooks.json. Each hook is a script that reads a JSON payload on stdin. For beforeShellExecution, it returns an allow, deny, or ask decision.
Hooks are project-scoped. Install them with
install.sh --projectinside a repository. Hook command paths are relative to the workspace root, so a user-scope (~/.cursor) install skips the hook config on purpose. After you install, quit Cursor completely (Cmd+Q) and reopen it, because a window reload does not register project hooks. Make sure the workspace is trusted.
| Hook handler | Event | Purpose |
|---|---|---|
guard-shell.sh |
beforeShellExecution |
Blocks destructive commands (rm -rf /, a force-push to main, a hard reset of a shared branch) and commits that contain forbidden anti-patterns (as any, @ts-ignore, empty catches) |
post-edit-lint.sh |
afterFileEdit |
Lints the edited file and reports issues right away. It never blocks. |
pre-commit-check.sh |
(library) | The anti-pattern checker that guard-shell.sh calls. It also works as a git pre-commit hook. |
To try the hooks without blocking anything, set OMC_HOOKS_OBSERVE=1. guard-shell.sh then logs what it would block and allows it. Use observe mode to check the hooks on your build before you let them block.
permissions.json is a tuned auto-review policy (autoRun.allow_instructions and block_instructions). Team Avatar agents run safe calls on their own, such as lints, tests, builds, and read-only git. Risky calls wait for review: destructive file operations, history rewrites, credential and secret access, and outbound network. The policy takes effect when a Run Mode is enabled in Cursor Settings > Agents > Approvals & Execution.
Hooks and auto-review are best-effort, not a security boundary. They prevent common mistakes and cut down on approval prompts, but they don't replace real sandboxing.
Validate the whole stack in one pass.
docs/E2E-TEST.mdis a runbook of 15 checks (model routing, hook enforcement, and auto-review) that Codex runs while you watch. Paste its Driver Prompt into Codex with Computer Use, and it fills in a pass and fail table against your live Cursor app.
Cursor Automations (Cursor 3.8 and later) start Team Avatar agents from events:
- A review comment on a PR sends Katara to fix it.
- An issue labeled
designsends Zuko to mock it up. - A Slack reaction (🔧, 🎨, or 🔍) dispatches the matching agent.
Cursor automations are cloud-only, with no config file you can commit yet, so these ship as ready-to-paste /automate recipes rather than installable config. See automations/.
You are Team Avatar. Use @toph to explore the codebase, @sokka to create a plan,
and @aang to implement. Verify with lints/build/tests. Keep going until done.
Or chain the slash commands: /plan add OAuth support with JWT tokens, then /build based on the plan above.
The Cursor edition installs 21 skills: 20 vendored from the community, plus cursor-image-generation, written for this repository. Each is a SKILL.md folder that Cursor discovers and offers to agents as domain knowledge. They ship inside the repository, so the installer never fetches third-party files and copies one tree. The installer adds them by default. To skip them, pass --no-skills.
Bundled skills (21)
| Skill | Source | Agents | What it provides |
|---|---|---|---|
| architect | thebushidocollective/han | Sokka | System architecture and high-level technical design |
| codebase-search | supercent-io/skills-template | Toph | Systematic search strategies for navigating large codebases |
| create-an-asset | anthropics/knowledge-work-plugins | Zuko | Generate tailored sales assets (landing pages, decks, one-pagers) |
| crafting-effective-readmes | community | Iroh | Templates and guidance for writing effective READMEs matched to project type |
| cursor-image-generation | tmcfarlane/team-avatar | Zuko | Rewrites short image requests into full prompts for Cursor image generation |
| debugging | oimiragieo/agent-studio | Katara | Systematic 4-phase debugging with root cause investigation |
| design-patterns-implementation | aj-geddes/useful-ai-prompts | Aang | Apply design patterns such as Singleton, Factory, Observer, and Strategy |
| docs-write | metabase/metabase | Iroh | Documentation following Metabase's conversational, user-focused style |
| documentation-engineer | charon-fan/agent-playbook | Iroh | Technical documentation for creating clear, comprehensive docs |
| documentation-writing | rysweet/amplihack | Iroh | Clear, discoverable docs following the Eight Rules and Diataxis framework |
| exploring-codebases | community | Toph | Semantic search using AST-aware expansion for full context |
| frontend-builder | daffy0208/ai-dev-standards | Appa | Modern React/Next.js frontend patterns and component architecture |
| implementing-figma-designs | onekeyhq/app-monorepo | Zuko | Implement Figma designs 1:1 using component libraries |
| mgrep-code-search | intellectronica/agent-skills | Toph | Semantic code search using mgrep for efficient exploration |
| planning | thebushidocollective/han | Sokka | Technical implementation planning and architecture design |
| refactoring | eyadsibai/ltk | Katara, Momo | Code restructuring, renaming, extraction, and migration |
| refactoring-patterns | wondelai/skills | Aang, Katara, Momo | Named refactoring transformations to improve code structure |
| technical-roadmap-planning | aj-geddes/useful-ai-prompts | Sokka | Comprehensive technical roadmaps aligned with business goals |
| vercel-composition-patterns | vercel-labs/agent-skills | Appa | React composition patterns that scale |
| vercel-react-best-practices | vercel-labs/agent-skills | Aang, Appa, Momo | React and Next.js performance optimization from Vercel Engineering |
| web-design-guidelines | vercel-labs/agent-skills | Zuko | Web Interface Guidelines compliance for UI review |
To add your own skill, create a SKILL.md folder under .cursor/skills/ (project) or ~/.cursor/skills/ (user). Cursor discovers it on its own.
No. The orchestrator delegates on its own. Slash commands such as /plan, /build, and /fix give you explicit control when you want it.
Yes, if your plan includes agent mode with subagents.
Run the install command again with --force (-Force on Windows).
Run the install command with --uninstall (-Uninstall on Windows).
Install the plugin from Install. It has the 9 characters and 58 skills built for those tools. The installer's --claude and --codex flags still work, but they copy only the Cursor edition.
The Cursor edition adapts oh-my-openagent (formerly oh-my-opencode): agent specialization, parallel dispatch, and phased orchestration, applied to Cursor's native Task subagents. The Claude Code and Codex plugin adapts pstack, as The honest version explains.
Contributions that improve clarity, behavior, or docs are welcome. See CONTRIBUTING.md for guidelines.
To work on the plugin, see Develop in the plugin README. To work on the Cursor edition, clone the repository and run bash install.sh (macOS and Linux) or .\install.ps1 (Windows) to install from source. Changes to agents, rules, commands, or hooks take effect after you reinstall.
To report a vulnerability, see SECURITY.md.
MIT. See LICENSE. Steal it respectfully.