team-avatar

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

https://github.com/user-attachments/assets/61db75bb-73e7-46d8-8863-fe9bbb8fad8c

App screens are recreated from this repository's real runs and files. Narration is an AI clone of the author's voice.

Origin story

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.

The honest version

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.

See it work

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.

Install

Claude Code:

claude plugin marketplace add tmcfarlane/team-avatar && claude plugin install team-avatar@team-avatar

Codex:

codex plugin marketplace add tmcfarlane/team-avatar && codex plugin add team-avatar@team-avatar

Codex 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.

Other harnesses

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-avatar

Keep 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.

Team Avatar for Cursor (the original oh-my-cursor)

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

Install the Cursor edition

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 | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/tmcfarlane/team-avatar/main/install.ps1 | iex

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              # Remove

Windows 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

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