tmcfarlane/oh-my-cursor

An Avatar-themed AI dev team for Cursor. 8 specialist agents, real per-model routing, and hooks that block bad commits — pure config files, no runtime, no wrapper CLI. Created by ZeroClickDev

v0.4.1 — Hardening (June 28, 2026, validated on Cursor 3.9.8: 13/15 → 15/15): a git pre-commit backstop catches as any/@ts-ignore commits even when the agent commits via Cursor’s native git path (which bypasses the shell hook), and credential-file reads (~/.ssh, ~/.aws, *.pem, …) are now held deterministically. See CHANGELOG.

v0.4.0 — Enforcement + Automation (June 26, 2026, validated live on Cursor 3.8.23): hooks that block an agent’s destructive commands and as any/@ts-ignore commits · an auto-review policy that holds risky calls (~84% fewer prompts) · paste-in /automate recipes · Windows parity. See the validated reference · contributions welcome.

Quick Start (One Command)

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/tmcfarlane/oh-my-cursor/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/tmcfarlane/oh-my-cursor/main/install.ps1 | iex

What Is This?

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

Each agent routes to its own model via Cursor’s model: field (per-agent routing). The catch: an invalid slug silently downgrades instead of erroring — so every slug here is verified against a real build (VALIDATION.md).

Contents

• Quick Start
• What Is This?
• Agents
• How to Install
• Slash Commands
• Orchestration Modes
• Architecture
• Skills
• FAQ
• Contributing
• License

The Orchestrator

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.

Team Avatar – The Agents

Eight specialized agents, each mapped to an Avatar character with a dedicated model and role. Expand any agent for skills and working screenshots.

                    

Model Policy

Default model: Composer 2.5 (composer-2.5-fast). See Cursor model docs for current availability and routing behavior. Higher speed, uses Cursor’s Auto + Composer pool. (#20, #21)

Exceptions:

Coordinator-spawned workers 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.

How to Install

Requirements: Cursor 3.4+ with agent mode (subagents). No external runtime.

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/tmcfarlane/oh-my-cursor/main/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/tmcfarlane/oh-my-cursor/main/install.ps1 | iex

What Gets Installed

First-time rule activation: Cursor may require you to approve the orchestrator rule. Open ~/.cursor/rules/orchestrator.mdc and click “Always Allow” when prompted (one-time step).

Upgrading from v0.1: The installer auto-removes old agent files (hephaestus, prometheus, atlas, etc.).

Per-Agent Model Routing

Cursor’s model: field in agent frontmatter routes each agent to a specific model (Cursor docs). It must be an exact, valid Cursor Task-tool slug — it does not accept arbitrary alias strings:

---
model: composer-2.5-fast # fast executor pool
---

---
model: gemini-3.1-pro # multimodal tasks
---

⚠️ An unrecognized slug does not error — it silently falls back to composer-2.5-fast. A typo or stale name looks like it “works” while quietly running the wrong model. Always use a verified slug and confirm routing (see VALIDATION.md). Omitting model: makes a subagent inherit its parent’s model.

Valid slugs (Cursor 3.8.x, verified 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, kimi-k2.5.

Slugs change between Cursor versions, and the docs don’t list the gotcha. Re-verify against your build before relying on routing — the VALIDATION.md sweep makes it a 2-minute check.

Slash Commands

Type these in Cursor’s chat to invoke specific workflows:

Image generation (Cursor agent)

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.

Two Orchestration Modes

Avatar State (Default)

Coordinated, tiered orchestration. The orchestrator auto-detects which agents to dispatch based on request signals.

Cactus Juice Mode

Activated via /cactus-juice. Trades depth for massive parallelism:

1. Root decomposes your request into 5–10 independent micro-tasks (single-file scope)
2. Up to 10 subagents spawn simultaneously using model: fast
3. Workers write low cognitive complexity code
4. Root collects results, verifies consistency, fixes integration issues

Architecture

flowchart TD
  U["You (root thread)"] --> R["orchestrator.mdc(Team Avatar)"]

  R --> IG{"Intent gatewhat did the user ask?"}

  IG -->|"search / 'how does X work?'"| T["Task(toph)Seer"]
  IG -->|"ambiguous / complex scope"| S["Task(sokka)Strategist"]
  IG -->|"visual assets"| Z["Task(zuko)Firebender"]

  IG -->|"complex feature"| PLAN["Task(sokka) → plan"]
  PLAN --> IMPL["Task(aang / katara)Coordinators"]

  IMPL -->|"spawns"| T2["toph (fast)"]
  IMPL -->|"spawns"| M2["momo (fast / inherited)"]

  IG -->|"task list"| AP["Task(appa)Heavy Lifter"]
  AP -->|"spawns"| M3["momo"]

  IG -->|"quick task"| MO["Task(momo)Scout"]

  IMPL --> V{"Verificationlints / build / tests"}
  V -->|pass| DONE["Done"]
  V -->|fail| FR["Failure recovery(retry → aang → user)"]

  subgraph swarmNote ["Swarm Mode (Cursor 3.4+)"]
    N1["Coordinators spawn workers async.Max depth = 2. Workers are leaf nodes."]
  end

Async Subagents (Cursor 3.4+)

Two-tier swarm: Coordinators (Aang, Sokka, Katara, Appa) spawn Workers (Toph, Momo) as leaf nodes. Zuko is root-only.

Hooks (Cursor agent-loop)

System-level enforcement that doesn’t rely on agents remembering to verify. Wired through Cursor’s hooks system via .cursor/hooks.json — each hook is a script that receives a JSON payload on stdin and (for beforeShellExecution) returns an allow/deny/ask decision.

Hooks are project-scoped. Install them with install.sh --project inside a repo; hook command paths are relative to the workspace root, so a user-scope (~/.cursor) install deliberately skips the hook config. After installing, fully restart Cursor (Cmd+Q) — a window reload is not enough to register project hooks — and ensure the workspace is trusted.

Observe mode: set OMC_HOOKS_OBSERVE=1 to run guard-shell.sh non-blocking — it logs what it would block without denying. Use this to validate hooks on your build before trusting them to block.

Auto-review policy (permissions.json)

Ships a tuned auto-review policy (autoRun.allow_instructions / block_instructions) so Team Avatar agents auto-run safe calls (lints, tests, builds, read-only git) and hold risky ones (destructive fs, history rewrites, credential/secret access, outbound network) for review. 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 reduce footguns and approval spam, but don’t replace real sandboxing.

Validate the whole stack in one pass. docs/E2E-TEST.md is a Codex-driven runbook (15 checks: model routing + hook enforcement + auto-review) you run attended — paste its Driver Prompt into Codex with Computer Use and it fills in a pass/fail table against your live Cursor app.

Automations (event-driven dispatch)

Fire Team Avatar agents from real-world events using Cursor Automations (3.8+): PR review comment → Katara fixes it; issue labeled design → Zuko mocks it up; Slack 🔧/🎨/🔍 reaction → routed dispatch. Cursor automations are cloud-only (no committable config file yet), so these ship as ready-to-paste /automate recipes, not installable config. See automations/.

Prompting Tips

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.

Skills

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.

Custom skills: Create a SKILL.md directory under .cursor/skills/ (project) or ~/.cursor/skills/ (user). Cursor auto-discovers it.

FAQ

Do I need to manually choose agents?

No — the orchestrator auto-delegates. Slash commands (/plan, /build, /fix, etc.) give explicit control when you want it.

Will this work on any Cursor plan?

Yes, if your plan supports agent mode / subagents.

How do I update?

Re-run the install command with --force (or -Force on Windows).

How do I uninstall?

Re-run with --uninstall (or -Uninstall on Windows).

Claude Code / Codex?

Yes — install with --claude --codex (or -AlsoClaude -AlsoCodex).

Origin Story

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.

Inspiration

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.

Star History

Contributing

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.

Security

To report a vulnerability, see SECURITY.md.

License

MIT. See LICENSE - Steal It Respectfully!