Multi-agent philosophy for Cursor subagents. Nothing but config files.
Created by ZeroClickDev
NOW USING UNDOCUMENTED FEATURES OF CURSOR!
April 14, 2026 — Welcome @bastien70 to Team Avatar! Two fantastic PRs just landed:
- Composer 2 Fast migration — All default agents now run on Composer 2 Fast, aligning with Cursor's Auto + Composer pool for lower latency and cost (#20)
- Zuko gets Nana Banana — Zuko now has image generation capabilities powered by Nana Banana, leveling up the Firebender's visual toolkit
These contributions were so solid that @bastien70 has been added as a CODEOWNER — they can now approve PRs from other contributors. Welcome to the project! 🎉
Want to contribute too? Contributions welcome!
macOS / Linux:
curl -fsSL https://raw.githubusercontent.com/tmcfarlane/oh-my-cursor/main/install.sh | bashWindows (PowerShell):
irm https://raw.githubusercontent.com/tmcfarlane/oh-my-cursor/main/install.ps1 | iex8 agent manifests, 8 slash commands, hooks, and one orchestration rule — themed around Avatar: The Last Airbender. No external runtime, no wrapper CLI — just Cursor's built-in Task subagents and Markdown config files.
Uses undocumented custom model aliases for per-agent model routing. Unofficial — may change.
- Quick Start
- What Is This?
- Agents
- How to Install
- Slash Commands
- Orchestration Modes
- Architecture
- Skills
- FAQ
- Contributing
- License
The orchestrator rule (orchestrator.mdc) rewires how the root thread thinks. The root becomes a pure dispatcher — its only permitted tools are Task, TodoWrite, AskQuestion, and SwitchMode. All work flows through specialist agents.
Here's a real example of the root thread's internal 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 → write), and mandatory task tracking via TodoWrite.
Eight specialized agents, each mapped to an Avatar character with a dedicated model and role. Expand any agent for skills and working screenshots.
Aang — The Avatar · composer-2-fast
Deep multi-file executor + 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-4.7-opus-max-thinking
Planning, ambiguity analysis, plan review. The brain behind every mission.
Ask First, Dispatch Second — The orchestrator clarifies before sending agents
Skills: architect · planning · technical-roadmap-planning
Katara — The Healer · composer-2-fast
Disciplined implementation, debugging, methodical fixes. Mends broken code.
Precision Healer — Surgical debugging, smallest possible fix
Skills: debugging · refactoring · refactoring-patterns
Zuko — The Firebender · gemini-3.1-pro
Visual design: image generation, icons, 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-fast
Codebase search, external docs, 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-fast
Systematic task list execution. Carries the team.
Plan Executor — Systematic task list execution, one step at a time
Skills: frontend-builder · vercel-composition-patterns · vercel-react-best-practices
Momo — The Scout · composer-2-fast
Quick focused tasks. Small, agile, independent.
Speed Demon — Parallel micro-tasks, maximum speed
Skills: refactoring · refactoring-patterns · vercel-react-best-practices
Iroh — The Storyteller · claude-4.7-opus-max-thinking
Documentation specialist. Sole owner of README, CHANGELOG, and all 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
Default model: Composer 2 Fast (composer-2-fast). See the Composer 2 docs, which also apply to the Fast variant. Higher speed, uses Cursor’s Auto + Composer pool. (#20, #21)
Exceptions:
| Agent | Model | Reason |
|---|---|---|
| Sokka | claude-4.7-opus-max-thinking |
Maximum reasoning for complex planning |
| Iroh | claude-4.7-opus-max-thinking |
Long-form documentation quality |
| Zuko | gemini-3.1-pro |
Multimodal / visual stack |
Coordinator-spawned workers may use Cursor’s fast tier or inherit the coordinator’s model. If a workflow regresses on Composer 2 Fast, change model: in the agent’s markdown file.
Requirements: Cursor with agent mode (subagents). No external runtime.
curl -fsSL https://raw.githubusercontent.com/tmcfarlane/oh-my-cursor/main/install.sh | bashMore options
bash -s -- --project # Install to this project only (./.cursor/)
bash -s -- --claude --codex # Also install for Claude Code and Codex
bash -s -- --no-skills # Skip skills installation
bash -s -- --dry-run # Preview changes
bash -s -- --force # Update/overwrite existing files
bash -s -- --uninstall # Uninstall
bash -s -- --disable # Disable orchestration (agents stay)
bash -s -- --enable # Re-enable orchestrationAppend these flags to the curl ... | bash one-liner above. Hacking locally? Clone the repo, then run bash install.sh.
irm https://raw.githubusercontent.com/tmcfarlane/oh-my-cursor/main/install.ps1 | iexMore options
# PowerShell 7+ / Windows 11 one-liner with flags:
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/tmcfarlane/oh-my-cursor/main/install.ps1))) -Scope project -Force
# Or clone and run locally (all versions):
git clone https://github.com/tmcfarlane/oh-my-cursor.git && cd oh-my-cursor
.\install.ps1 # Default (user scope)
.\install.ps1 -Scope project # Project scope
.\install.ps1 -AlsoClaude -AlsoCodex # Cross-tool compat
.\install.ps1 -NoSkills # Skip skills
.\install.ps1 -Force # Overwrite
.\install.ps1 -Uninstall # RemoveOn Windows PowerShell 5.1,
irm | iexonly supports default install. For flags, clone the repo.
| 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/ |
— |
--codex |
Also .codex/agents/ |
Also .codex/rules/ |
Also .codex/commands/ |
Also .codex/hooks/ |
— |
--no-skills |
✓ | ✓ | ✓ | ✓ | Skipped |
First-time rule activation: Cursor may require you to approve the orchestrator rule. Open
~/.cursor/rules/orchestrator.mdcand click "Always Allow" when prompted (one-time step).
Upgrading from v0.1: The installer auto-removes old agent files (hephaestus, prometheus, atlas, etc.).
Cursor’s model: field in agent frontmatter accepts arbitrary model alias strings — not just built-in options. This enables per-agent model routing:
---
model: composer-2-fast # fast agent work
------
model: gemini-3.1-pro # multimodal tasks
---Undocumented — may change without notice. Works as of February 2026. If removed, swap
model:to any picker-supported string; the rest of oh-my-cursor still works.
Type these in Cursor's chat to invoke specific workflows:
| Command | Agent | Purpose |
|---|---|---|
/plan |
Sokka | Full planning pipeline: ambiguity analysis, plan creation, self-review |
/build |
Aang | Deep multi-file implementation with verification |
/search |
Toph | Multi-angle codebase + docs exploration |
/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): icons, mockups, prompts via cursor-image-generation skill |
/cactus-juice |
Swarm | Decompose into micro-tasks, spawn up to 10 parallel workers |
The agent can generate images via Google Nano Banana Pro; previews save under assets/ by default. Team Avatar routes visual generation to Zuko, which uses the cursor-image-generation skill (skills/cursor-image-generation/SKILL.md) to rewrite short user requests into full prompts, then iterate. Use /image or delegate Task(zuko) for image-only work.
Coordinated, tiered orchestration. The orchestrator auto-detects which agents to dispatch based on request signals.
Activated via /cactus-juice. Trades depth for massive parallelism:
- Root decomposes your request into 5–10 independent micro-tasks (single-file scope)
- Up to 10 subagents spawn simultaneously using
model: fast - Workers write low cognitive complexity code
- Root collects results, verifies consistency, 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 2.5+)"]
N1["Coordinators spawn workers async.<br/>Max depth = 2. Workers are leaf nodes."]
end
Two-tier swarm: Coordinators (Aang, Sokka, Katara, Appa) spawn Workers (Toph, Momo) as leaf nodes. Zuko is root-only.
| Pattern | How It Works |
|---|---|
| Fire-and-Continue | Spawn Toph in background, continue working, collect results later |
| Fire-and-Collect | Spawn multiple Momo workers, wait for all, verify each |
| Research-then-Act | Parallel Toph research, then use findings to guide implementation |
System-level enforcement that doesn't rely on agents remembering to verify:
| Hook | Purpose |
|---|---|
post-edit-lint.sh |
Automatically run lints after agent edits |
pre-commit-check.sh |
Enforce hard constraints (as any, empty catches, @ts-ignore) before commits |
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 use slash commands: /plan add OAuth support with JWT tokens then /build based on the plan above.
19 bundled skills vendored from the community. Each is a SKILL.md directory that Cursor auto-discovers and presents to agents as domain knowledge. Bundled in-repo for security (no fetching third-party files at install time) and efficiency (single file copy). Installed by default; use --no-skills to skip.
| 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 |
| 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 (Singleton, Factory, Observer, Strategy, etc.) |
| 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 |
Custom skills: Create a SKILL.md directory under .cursor/skills/ (project) or ~/.cursor/skills/ (user). Cursor auto-discovers it.
No — the orchestrator auto-delegates. Slash commands (/plan, /build, /fix, etc.) give explicit control when you want it.
Yes, if your plan supports agent mode / subagents.
Re-run the install command with --force (or -Force on Windows).
Re-run with --uninstall (or -Uninstall on Windows).
Yes — install with --claude --codex (or -AlsoClaude -AlsoCodex).
Upgraded to Cursor Ultra with 9 days left to burn ~$300 in tokens. Built agent swarms to do real work while responsibly (irresponsibly) optimizing token burn. Turns out all it takes is dropping Markdown config files into Cursor + one orchestration rule.
Adapted from oh-my-opencode (32k+ stars) — agent specialization, parallel dispatch, phased orchestration — applied to Cursor's native Task subagents. No plugin system, no wrapper CLI.
Contributions that improve clarity, behavior, or docs are welcome. See CONTRIBUTING.md for guidelines.
Local development: Clone the repo and run bash install.sh (macOS/Linux) or .\install.ps1 (Windows) to install from source. Changes to agents, rules, commands, or hooks take effect after reinstalling.
To report a vulnerability, see SECURITY.md.
MIT. See LICENSE - Steal It Respectfully!