Recursive Claude Code Subagents

A recursive task execution system for Claude Code that breaks down complex projects into atomic tasks and executes them using specialized agents.

Installation

Prerequisites: Claude Code in Yolo Mode

This system works best with Claude Code running in "yolo mode" (auto-approve all tool calls). Add this helper function to your shell profile (.bashrc, .zshrc, etc.):

clx() {
  if [[ "$1" == "update" ]]; then
    npm install -g @anthropic-ai/claude-code
  else
    npm install -g @anthropic-ai/claude-code
    claude --dangerously-skip-permissions "$@"
  fi
}

Then use clx instead of claude to run with auto-approval, or clx update to update Claude Code.

1. Copy Agents

Copy all agent files from the agents/ folder to your Claude Code agents directory:

cp agents/*.md ~/.claude/agents/

2. Install Dev-Browser Skill

The integration-tester and task-validator agents use the dev-browser skill for UI/frontend testing. Install it with:

/plugin marketplace add sawyerhood/dev-browser
/plugin install dev-browser@sawyerhood/dev-browser

Usage

Invoke the recursive orchestrator using @recursive-orchestrator to execute complex multi-task projects.

Example Prompts

Reference the agent first:

@recursive-orchestrator Build a REST API with user authentication and a React dashboard

Describe requirements, then invoke:

I need a full-stack e-commerce app with:
- User registration and login
- Product catalog with search
- Shopping cart and checkout
- Admin dashboard for inventory

Use @recursive-orchestrator

With a specification file:

@requirements.md implement this project using @recursive-orchestrator

For an existing task list:

@tasks.json execute all tasks using @recursive-orchestrator

What Happens

The system will:

1. Decompose the project into atomic tasks
2. Create a .recursive-tasks.json state file
3. Dispatch tasks to specialized agents by category
4. Validate completed work
5. Recursively continue until all tasks are complete

Agent Hierarchy

recursive-orchestrator (entry point)
    │
    ├── task-decomposition-expert (breaks project into tasks)
    │
    └── recursive-executor (runs the loop)
            │
            ├── task-dispatcher (routes by category)
            │       │
            │       └── Specialized Agents:
            │           ├── frontend-developer
            │           ├── backend-architect
            │           ├── ai-engineer
            │           ├── code-reviewer
            │           ├── security-auditor
            │           ├── performance-engineer
            │           ├── ui-ux-designer
            │           ├── python-pro
            │           ├── prompt-engineer
            │           └── fullstack-developer (fallback)
            │
            ├── task-validator (validates completed work)
            │
            └── integration-tester (final E2E testing)

Task Categories

Category	Agent	Specialization
frontend	frontend-developer	React, UI components, responsive design
backend	backend-architect	APIs, microservices, database schema
ai	ai-engineer	LLM integration, RAG, embeddings
testing	code-reviewer	Code quality, test coverage
security	security-auditor	Vulnerabilities, auth, OWASP
performance	performance-engineer	Optimization, profiling, caching
ui-ux	ui-ux-designer	Wireframes, design systems
python	python-pro	Python-specific implementation
prompts	prompt-engineer	Prompt design and optimization
(fallback)	fullstack-developer	Multi-category tasks

Acknowledgments

• dev-browser by SawyerHood - Browser automation skill for UI testing
• claude-code-templates by davila7 - Agent code ideas and templates

License

MIT

Author

Pratik Desai (@chheplo)