Smart Agent Router

Stop spawning every subagent for every task.

Smart Agent Router gives Claude Code a lightweight routing layer:

• simple edits → main agent only
• unclear codebase tasks → researcher agent
• frontend tasks → frontend agent
• backend/API tasks → backend agent
• full-stack tasks → researcher + frontend + backend
• risky changes → reviewer first

Spend tokens only when parallelism pays off.

1. What is this?

Smart Agent Router is a small CLI that installs routing rules and subagent templates into a project so Claude Code (or Codex) can decide, at the start of every task, how much help it actually needs.

It writes three things into your project:

• CLAUDE.md — a routing rule block the main agent reads before each task
• .claude/agent-router.yaml — the structured routing config
• .claude/agents/*.md — a small set of subagent templates

It does not run agents by itself. It installs the rules and templates that make Claude Code route well. Think of it as a config installer, not a runtime.

2. Why not just use more agents?

Because more agents is not free.

Every subagent spends tokens, adds latency, and adds coordination overhead. For a one-line copy change, spinning up a researcher, a frontend agent, and a reviewer is pure waste.

Smart Agent Router encodes one idea: right agent, right time, minimum cost.

• Simple task → main agent does it directly, no subagents.
• Medium task → 1–2 subagents.
• Complex task → 2–3 subagents working in parallel.
• Risky / large task → plan or review first, don't blast the codebase.

You spend tokens to buy speed and safety only when parallelism or context isolation actually pays off.

3. Quick start

npx smart-agent-router init

That installs the router into the current project. Then check it:

npx smart-agent-router doctor

No build step, no dependencies, no background service.

4. 30-second demo

See how the router classifies tasks without touching any files:

npx smart-agent-router demo

Task A: "Change the button text from Submit to Save"
  Complexity: S → Agents: none

Task B: "Understand the login flow in this project"
  Complexity: M → Agents: codebase-researcher

Task C: "Add a new dashboard page with a backend API"
  Complexity: L → Agents: codebase-researcher, frontend-agent, backend-agent

Task D: "Fix a failed Vercel deployment"
  Complexity: M/L → Agents: deploy-agent

5. Commands

| Command | What it does | |---|---| | init | Install router rules and agent templates into the current project | | doctor | Check whether the current project is ready | | demo | Show routing examples without changing files | | status | Show installed router files and agents | | add-agent <name> | Add one built-in agent template on demand | | remove | Remove the router block, and optionally the installed agents | | help | Show usage | | --version | Print the version |

smart-agent-router init [--mode minimal|recommended|aggressive|speed-first] \
                        [--preset default|web-app|ai-app|wechat-miniapp|docs-only|solo-founder] \
                        [--dry-run]
smart-agent-router remove [--dry-run] [--agents]

Run init --dry-run first if you want to preview every file before anything is written.

6. Modes

Modes control how aggressive the router is.

| Mode | Max subagents | Installs | |---|---|---| | minimal | 2 | researcher + reviewer only | | recommended (default) | 3 | the 6 core agents | | aggressive | 4 | all 9 agents | | speed-first | 6 | all 9 agents + a speed-first override block in CLAUDE.md |

speed-first is for when wall-clock speed matters and token cost does not. It tells the main agent to parallelize aggressively and spawn subagents when in doubt. It still skips subagents for trivial edits and strictly sequential tasks, because there spawning them is actually slower.

smart-agent-router init --mode minimal
smart-agent-router init --mode speed-first

7. Presets

Presets are curated agent sets for a kind of project.

| Preset | Best for | |---|---| | default | General projects (6 core agents) | | web-app | Frontend + backend web apps | | ai-app | LLM / AI pipeline products | | wechat-miniapp | WeChat mini-programs | | docs-only | Documentation repositories | | solo-founder | One person shipping end to end, deploys included |

smart-agent-router init --preset ai-app

If you pass both --mode and --preset, the agent list comes from the preset and the max-subagents number comes from the mode.

See docs/presets.md for details.

8. What files does it create?

your-project/
  CLAUDE.md                      # AGENT_ROUTER block appended or updated
  .claude/
    agent-router.yaml            # structured routing config
    agents/
      codebase-researcher.md
      frontend-agent.md
      backend-agent.md
      ai-pipeline-agent.md
      reviewer-agent.md
      docs-agent.md

• Existing CLAUDE.md and agent-router.yaml are backed up before any change (*.bak-YYYYMMDD-HHMMSS).
• Existing agent files are never overwritten — they are skipped.
• init only touches the current project. It does not write to ~/.claude.

9. How to use with Claude Code

After init, paste this into Claude Code at the start of a task:

请先读取 CLAUDE.md 和 .claude/agent-router.yaml。
根据任务复杂度选择最少但足够的子 Agent。
不要默认启动所有 Agent。
现在任务是：……

Claude Code reads the CLAUDE.md routing block, classifies the task as S / M / L / XL, and selects the smallest sufficient set of subagents — with a stated reason for each one it uses and each one it skips.

10. Customize agents

• Edit .claude/agent-router.yaml to change routing rules or max_subagents.
• Edit any file in .claude/agents/ to change an agent's behavior.
• Add your own agent: drop a new .md file into .claude/agents/.
• Add a built-in agent later: smart-agent-router add-agent test-agent.

See docs/customization.md.

11. Safety and rollback

• Every write to an existing file is preceded by a timestamped backup.
• --dry-run previews changes for both init and remove.
• Agent files are never overwritten.
• remove deletes only the router block by default; remove --agents also removes built-in agents, and never touches agents you wrote yourself.

Roll back manually at any time:

smart-agent-router remove          # remove the router block from CLAUDE.md
smart-agent-router remove --agents # also remove built-in agents

12. Philosophy

• More agents is not always better.
• Simple tasks should stay simple.
• Subagents exist for context isolation, parallel exploration, and risk reduction — not to look sophisticated.
• The main agent stays responsible for final decisions.
• Token spending should be intentional.

See docs/philosophy.md.

13. Roadmap

- run logs
- token/cost estimates
- better preset detection
- VS Code extension
- optional OpenAI Agents SDK / LangGraph backend

Honest scope

This project installs routing rules and subagent templates. It does not run agents by itself. It is not a multi-agent runtime, and it is not a replacement for LangGraph, CrewAI, AutoGen, or the OpenAI Agents SDK. It is a thin, transparent, reversible config layer for Claude Code.

License

MIT — see LICENSE.