Claude Sub-Agents Manager - AI-Powered Development Assistants for Claude Code

July 28, 2025 · View on GitHub

🚀 Supercharge Claude Code with Specialized AI Sub-Agents for Code Review, Testing, Debugging & More

Transform your development workflow with intelligent AI assistants that excel at specific programming tasks

Installation • Quick Start • Available Agents • Documentation • Contributing

🎯 What is Claude Sub-Agents Manager?

Claude Sub-Agents Manager is a powerful CLI tool that enhances Claude Code with specialized AI assistants designed for specific development tasks. Each sub-agent is an expert in its domain - from automated code reviews and test fixing to intelligent debugging and documentation generation. Install production-ready agents instantly or create custom agents tailored to your unique workflow needs.

✨ Why Claude Sub-Agents?

🧠 Specialized Intelligence: Each agent is an expert in its domain
⚡ Zero Configuration: Pre-built agents work out of the box
🎨 Fully Customizable: Create agents that match your workflow
🔄 Smart Context Management: Agents operate in isolated contexts
🛠️ Developer First: Built by developers, for developers
🔗 Context-Forge Integration: Seamlessly works with context-forge projects and PRPs

🎉 New in v1.4.0 - Context-Forge Integration

🛠️ Full Context-Forge Support: Automatic detection and smart integration
📦 Init Command: claude-agents init for one-command project setup
🧹 Uninstall Command: Bulk removal with cleanup options
📁 Smart Command Organization: No conflicts with existing context-forge commands
⚡ Concurrent Execution Rules: Enforces best practices for maximum performance
📝 CLAUDE.md Integration: Appends configuration without overwriting
🎯 PRP Awareness: Agents understand and work with your existing PRPs

🚀 Installation

NPM (Recommended)

npm install -g @webdevtoday/claude-agents

Yarn

yarn global add @webdevtoday/claude-agents

From Source

git clone https://github.com/webdevtodayjason/sub-agents.git
cd sub-agents
npm install
npm link

⚡ Quick Start

For New Projects

# Initialize all agents in your project
claude-agents init

# List available agents
claude-agents list

For Context-Forge Projects

# Initialize with context-forge awareness
claude-agents init --respect-context-forge

# Agents will:
# - Detect existing PRPs and CLAUDE.md
# - Place commands in .claude/commands/agents/
# - Append to CLAUDE.md without overwriting
# - Work alongside your existing setup

Example Agent Tasks

# Project Planning - Reads and understands your PRPs
claude-agents run project-planner --task "Create implementation roadmap from existing PRPs"
claude-agents run project-planner --task "Break down auth-prp into sprint tasks"

# API Development - PRP-aware implementation
claude-agents run api-developer --task "Implement user endpoints from feature-auth-prp.md"
claude-agents run api-developer --task "Create REST API following our conventions"

# Frontend Development
claude-agents run frontend-developer --task "Build login UI matching dark-theme-ui-prp"
claude-agents run frontend-developer --task "Create dashboard from feature-dashboard-prp.md"

# Testing & Quality
claude-agents run tdd-specialist --task "Create tests for authentication flow"
claude-agents run code-reviewer --task "Review API endpoints for security"
claude-agents run security-scanner --task "Scan authentication implementation"

# Documentation
claude-agents run api-documenter --task "Generate OpenAPI spec from implemented endpoints"
claude-agents run doc-writer --task "Update Implementation.md with progress"

# Debugging & Refactoring
claude-agents run debugger --task "Analyze login timeout issue"
claude-agents run refactor --task "Improve error handling in auth module"

# DevOps & Deployment
claude-agents run devops-engineer --task "Setup CI/CD for main branch"
claude-agents run devops-engineer --task "Create Docker configuration"

# Product & Marketing
claude-agents run product-manager --task "Create user stories from PRPs"
claude-agents run marketing-writer --task "Write feature announcement for auth system"

Using in Claude Code

# Via slash commands (in .claude/commands/agents/)
> /agent-review            # Triggers code review
> /agent-api              # Triggers API development
> /agent-debug login issue # Debug specific problem

# Via Task tool
> Task("project-planner: analyze all PRPs and create sprint plan")
> Task("api-developer: implement endpoints from feature-auth-prp.md")
> Task("frontend-developer: build UI from feature-dashboard-prp.md")

📋 Available Sub-Agents

Agent Name	Description	Slash Command
code-reviewer	Expert code review specialist for quality, security, and maintainability	`/review`
test-runner	Automated test execution specialist that runs tests and fixes failures	`/test [pattern]`
debugger	Expert debugging specialist for analyzing errors, stack traces, and fixing issues	`/debug [error]`
refactor	Code refactoring specialist for improving code structure, patterns, and maintainability	`/refactor [target]`
doc-writer	Documentation specialist for creating and updating technical documentation, API docs, and README files	`/document [type]`
security-scanner	Security vulnerability scanner that detects common security issues and suggests fixes	`/security-scan [path]`
shadcn-ui-builder	UI/UX specialist for designing and implementing interfaces using ShadCN UI components	`/ui` or `/shadcn`
project-planner	Strategic planning specialist for project decomposition and workflow management	`/plan [project]`
api-developer	Backend API development specialist for REST, GraphQL, and microservices	`/api [spec]`
frontend-developer	Frontend development specialist for modern web applications	`/frontend [feature]`
tdd-specialist	Test-Driven Development specialist for comprehensive testing strategies	`/tdd [component]`
api-documenter	API documentation specialist for OpenAPI, Swagger, and technical docs	`/apidoc [endpoint]`
devops-engineer	DevOps specialist for CI/CD, infrastructure automation, and deployment	`/devops [task]`
product-manager	Product management specialist for requirements, roadmaps, and user stories	`/product [feature]`
marketing-writer	Marketing content specialist for technical marketing and product messaging	`/marketing [content]`

🤖 Detailed Agent Descriptions

🔍 Code Reviewer

Your personal code quality guardian

Comprehensive security analysis
Best practices enforcement
Performance optimization suggestions
Clean code principles

# Install
claude-agents install code-reviewer

# Use
> /review

🧪 Test Runner

Intelligent test automation specialist

Auto-detects test frameworks
Fixes failing tests automatically
Improves test coverage
Supports all major languages

# Install
claude-agents install test-runner

# Use
> /test
> /test src/**/*.test.js

🐛 Debugger

Expert problem solver and bug hunter

Root cause analysis
Stack trace interpretation
Performance profiling
Memory leak detection

# Install
claude-agents install debugger

# Use
> /debug Cannot read property 'map' of undefined

🔧 Refactor Assistant

Code transformation specialist

Apply design patterns
Modernize legacy code
Improve code structure
Maintain functionality

# Install
claude-agents install refactor

# Use
> /refactor improve performance
> /refactor apply SOLID principles

📝 Documentation Writer

Technical writing expert

API documentation
README generation
Architecture docs
Code comments

# Install
claude-agents install doc-writer

# Use
> /document API
> /document architecture

🔒 Security Scanner

Vulnerability detection specialist

Secret detection
OWASP compliance
Dependency auditing
Security best practices

# Install
claude-agents install security-scanner

# Use
> /security-scan
> /security-scan src/api/

🎨 ShadCN UI Builder

Your expert UI/UX implementation specialist

Modern component-based UI development
Accessibility-first design approach
Responsive interface implementation
ShadCN component ecosystem expertise
Design system compliance

# Install
claude-agents install shadcn-ui-builder

# Use
> /ui create a login page
> /shadcn implement dashboard with sidebar

📋 Project Planner

Strategic planning and task decomposition expert

Project architecture design
Task breakdown and prioritization
Dependency mapping
Timeline estimation
Risk assessment

# Install
claude-agents install project-planner

# Use
> /plan e-commerce platform
> /plan microservices migration

🔌 API Developer

Backend development specialist

RESTful API design
GraphQL implementation
Microservices architecture
Database schema design
API security best practices

# Install
claude-agents install api-developer

# Use
> /api user authentication endpoints
> /api payment processing service

💻 Frontend Developer

Modern web interface specialist

React/Vue/Angular expertise
Responsive design implementation
State management
Performance optimization
Accessibility compliance

# Install
claude-agents install frontend-developer

# Use
> /frontend user dashboard
> /frontend shopping cart component

🧪 TDD Specialist

Test-driven development expert

Unit test creation
Integration testing
E2E test scenarios
Test coverage analysis
Mock and stub implementation

# Install
claude-agents install tdd-specialist

# Use
> /tdd UserService class
> /tdd API integration tests

📚 API Documenter

Technical documentation specialist

OpenAPI/Swagger specs
API endpoint documentation
Integration guides
SDK documentation
Example code generation

# Install
claude-agents install api-documenter

# Use
> /apidoc REST endpoints
> /apidoc GraphQL schema

🚀 DevOps Engineer

Infrastructure and deployment expert

CI/CD pipeline setup
Docker containerization
Kubernetes orchestration
Infrastructure as Code
Monitoring and logging

# Install
claude-agents install devops-engineer

# Use
> /devops GitHub Actions workflow
> /devops Kubernetes deployment

📊 Product Manager

Product strategy and planning specialist

User story creation
Feature specification
Roadmap planning
Requirements documentation
Stakeholder communication

# Install
claude-agents install product-manager

# Use
> /product user onboarding flow
> /product feature prioritization

✍️ Marketing Writer

Technical marketing content expert

Product launch materials
Technical blog posts
Feature announcements
Documentation marketing
Developer advocacy content

# Install
claude-agents install marketing-writer

# Use
> /marketing product launch post
> /marketing API feature announcement

## 📖 Documentation

### Command Reference

| Command | Description | Example |
|---------|-------------|---------|
| `init` | Initialize agents in project | `claude-agents init` |
| `init --respect-context-forge` | Init preserving context-forge | `claude-agents init --respect-context-forge` |
| `install` | Install agents interactively | `claude-agents install` |
| `install --all` | Install all available agents | `claude-agents install --all` |
| `install --project` | Install to project directory | `claude-agents install --project` |
| `list` | Show all agents | `claude-agents list` |
| `list --installed` | Show only installed agents | `claude-agents list --installed` |
| `enable <agent>` | Enable a disabled agent | `claude-agents enable code-reviewer` |
| `disable <agent>` | Disable an agent | `claude-agents disable test-runner` |
| `remove <agent>` | Remove specific agent | `claude-agents remove debugger` |
| `uninstall` | Bulk uninstall with options | `claude-agents uninstall --all --clean` |
| `info <agent>` | Show agent details | `claude-agents info debugger` |
| `create` | Create a custom agent | `claude-agents create` |
| `run <agent>` | Run agent independently | `claude-agents run marketing-writer --task "write launch post"` |
| `dashboard` | Launch web dashboard | `claude-agents dashboard` |

### Independent Agent Execution

Run agents outside of Claude Code for automation and scripting:

```bash
# Run with inline task
claude-agents run marketing-writer --task "Write launch announcement for v2.0"

# Run with task file
claude-agents run api-developer --file api-spec.md

# Interactive mode
claude-agents run tdd-specialist --interactive

Web Dashboard

Monitor and manage your agents through the web interface:

# Start dashboard on port 7842
claude-agents dashboard

# Custom port
claude-agents dashboard --port 8080

Dashboard features:

Real-time agent status
Task execution history
Memory system viewer
Performance metrics
Quick agent actions

Creating Custom Agents

Interactive Creation

claude-agents create

Manual Creation

Create ~/.claude/agents/my-agent.md:

---
name: my-agent
description: What this agent does and when to use it
tools: Read, Edit, Grep, Bash
---

You are an expert in [DOMAIN]. Your role is to [PURPOSE].

When invoked, you will:
1. [STEP 1]
2. [STEP 2]
3. [STEP 3]

Always ensure [KEY PRINCIPLE].

Installation Scopes

User Scope (~/.claude/agents/)

Available in all projects
Personal agents
Default installation location

Project Scope (.claude/agents/)

Project-specific agents
Shared with team via version control
Use --project flag

Advanced Configuration

State Management

Agent states are tracked in .claude-agents.json:

{
  "installedAgents": {
    "code-reviewer": {
      "version": "1.0.0",
      "scope": "user",
      "installedAt": "2024-01-20T10:00:00Z"
    }
  },
  "enabledAgents": ["code-reviewer"],
  "disabledAgents": []
}

Hooks System

The hooks system enables automated workflows and agent coordination. Each agent can define hooks that trigger on specific events.

Hook Types

Hook Type	Description	Trigger
`PostToolUse:Edit`	After file edits	Any file modification
`PostToolUse:Write`	After file creation	New file written
`PostToolUse:Bash`	After command execution	Bash commands run
`PreToolUse`	Before any tool use	Tool about to run
`TaskComplete`	After task completion	Agent finishes task
`Stop`	On conversation end	Session terminating

Hook Actions

{
  "PostToolUse:Edit": {
    "condition": "file.endsWith('.js')",
    "commands": ["npm run lint", "npm test"]
  },
  "TaskComplete": {
    "notify": "Task {{task_name}} completed",
    "store": "agent:{{agent_name}}:last_task"
  }
}

Example: Auto-Review Hook

Create hooks for automatic code review after edits:

{
  "hooks": {
    "PostToolUse:Edit": [{
      "matcher": "\\.(js|ts|py)$",
      "hooks": [{
        "type": "command",
        "command": "echo 'Consider running /review' >&2"
      }]
    }]
  }
}

Example: Test Runner Hook

Automatically run tests after code changes:

{
  "PostToolUse:Edit": {
    "condition": "file.includes('src/')",
    "commands": ["npm test -- --watch=false"]
  }
}

Fork the repository
Create your feature branch (git checkout -b feature/amazing-agent)
Commit your changes (git commit -m 'Add amazing agent')
Push to the branch (git push origin feature/amazing-agent)
Open a Pull Request

Adding New Agents

Create agent structure:

agents/
└── your-agent/
    ├── agent.md       # Agent definition
    ├── metadata.json  # Agent metadata
    └── hooks.json     # Optional hooks

Add slash command:

commands/
└── your-command.md

Submit PR with description

🐛 Troubleshooting

Agent Not Found After Global Install?

# Enable debug mode to see where agents are being searched
DEBUG=claude-agents claude-agents run project-planner --task "test"

# Check npm global installation path
npm list -g @webdevtoday/claude-agents

# Verify agents are included in the package
ls -la $(npm root -g)/@webdevtoday/claude-agents/agents/

Agent Not Working?

# Check installation
claude-agents list

# Verify agent status
claude-agents info <agent-name>

# Re-enable if disabled
claude-agents enable <agent-name>

Debug Mode

# Run Claude with debug output
claude --debug

# Run claude-agents with debug output
DEBUG=claude-agents claude-agents run <agent> --task "test"

Common Issues

Permission denied: Use sudo for global install
Agent not found: Check spelling and installation
Command not working: Ensure Claude Code is updated
"Agent not found" error: Enable debug mode to see search paths

📊 Release Notes

Version 1.4.0 (Latest) - Context-Forge Integration

🛠️ Context-Forge Support: Full integration with context-forge projects
📦 Init Command: One-command setup with claude-agents init
🧹 Uninstall Command: Bulk removal with cleanup options
🎯 PRP Awareness: Agents understand and work with existing PRPs
📁 Smart Commands: Organized in .claude/commands/agents/ to avoid conflicts
⚡ Concurrent Execution: CLAUDE.md rules for maximum performance
📝 Safe Integration: Appends to CLAUDE.md without overwriting
🔧 Bug Fixes: Project scope installation now works correctly