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

🙏 Acknowledgments

This project is forked from https://github.com/webdevtodayjason/sub-agents.git. A warm thanks to webdevtodayjason for the excellent project contribution and foundation!

\ud83d\udd04 Major Update: Now fully compatible with Claude Code's native agent format! Use the migrate command to update existing agents.

🎯 What is Claude Sub-Agents Manager?

Claude Sub-Agents Manager is a complementary CLI tool for Claude Code that helps you discover, install, and optimize AI agents. It fully supports Claude Code's native agent format while adding powerful features like bulk operations, description optimization for better auto-delegation, and quality validation. Think of it as a package manager for Claude Code agents.

✨ Why Use This Tool?

• 🧠 Agent Discovery: Browse and install community agents easily
• ⚡ Bulk Operations: Install, update, or validate multiple agents at once
• 🎨 Description Optimization: Improve agent descriptions for better auto-delegation
• 🔍 Quality Validation: Ensure agents follow best practices
• 🔄 Format Migration: Convert legacy agents to Claude Code format
• 🛠️ Developer Friendly: Simplifies agent management workflow

🚀 Installation

NPM (Recommended)

npm install -g @zamaz/claude-agents

Yarn

yarn global add @zamaz/claude-agents

From Source

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

🔄 Updating

Check Current Version

claude-agents --version
# or
claude-agents version

Update to Latest

# NPM
npm update -g @zamaz/claude-agents

# Yarn
yarn global upgrade @zamaz/claude-agents

# From source
cd sub-agents
git pull
npm install
npm link --force

Check for Updates

# Manual check
claude-agents version

# Automatic check on every run
# (notifies when updates are available)

⚡ Quick Start

# See what's available
claude-agents list

# Install your first agent interactively
claude-agents install

# Or install all agents at once
claude-agents install --all

# Install specific agents directly (NEW!)
claude-agents install code-reviewer test-runner

# Sync externally installed agents
claude-agents sync

# Agents now use description-based auto-delegation
# In Claude Code, just describe what you need:
> "Review my recent code changes"
> "Run the tests and fix any failures"
> "Debug this TypeError in production"

🔄 Keeping Agents in Sync

Claude Code may install agents directly to ~/.claude/agents/. Use the sync command to register these agents:

# Detect and register externally installed agents
claude-agents sync

# Enable automatic synchronization
claude-agents config autosync on

# Check sync status
claude-agents config autosync

The sync feature ensures all agents are properly tracked and managed, regardless of how they were installed. See SYNC_PROCESS.md for details.

📋 Available Sub-Agents

🤖 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 in Claude Code (auto-delegation)
> "I need to review my recent changes for security issues"

🧪 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/

📖 Documentation

📚 Command Reference

🔄 Updating Agents

Keep your agents up-to-date with the latest improvements and features:

Update Commands

# Interactive update - select which agents to update
claude-agents update

# Update a specific agent
claude-agents update code-reviewer

# Update all installed agents at once
claude-agents update --all

# Force update without confirmation prompt
claude-agents update --all --force

# Preserve custom modifications during update
claude-agents update --all --preserve-custom

Using Make

# Update all agents quickly
make update-agents

# Update specific agent
make update-agent AGENT=code-reviewer

# List installed agents first
make list-agents

What Gets Updated

• Agent Definitions - Latest prompts and configurations
• Metadata - Version information and timestamps
• Hooks - Any associated automation hooks
• Slash Commands - Corresponding command files

🔄 New Features for Claude Code Compatibility

Migrate Existing Agents

# Convert old format to Claude Code format
claude-agents migrate

# With options
claude-agents migrate --cleanup  # Remove old directories after migration

Optimize Agent Descriptions

# Improve descriptions for better auto-delegation
claude-agents optimize

# Optimize specific agent
claude-agents optimize code-reviewer

Validate Agent Quality

# Check agent format and quality
claude-agents validate

# Detailed validation
claude-agents validate --verbose

Creating Custom Agents

Simple Agent Creation

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

---
name: my-agent
description: Automatically handles X when Y occurs. Use when dealing with Z tasks.
tools: Read, Edit, Grep  # Optional - inherits all if omitted
---

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

## Process
When invoked, immediately:
1. [STEP 1]
2. [STEP 2]
3. [STEP 3]

\ud83d\udcdd Agent Format (Claude Code Compatible)

Agents are now single .md files with YAML frontmatter:

---
name: agent-name
description: Clear description with trigger words for auto-delegation
tools: Read, Grep, Glob  # Optional - inherits all if omitted
---

Agent system prompt here...

Key Points:

• No more slash commands - uses description-based auto-delegation
• No separate metadata.json or hooks.json files
• Tools are optional - agents inherit all tools if not specified
• Descriptions should include trigger words for better matching

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": []
}

Hook Integration

Trigger agents automatically with hooks:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "echo 'Consider running /review' >&2"
      }]
    }]
  }
}

🌟 Our Ecosystem

Check out our other tools for Claude Code:

🪝 Claude Hooks Manager

Powerful hook management system for Claude Code automation

🔨 Context Forge

Our flagship tool for intelligent context generation and management

🚫 Gitignore Support

Claude agents now respect gitignore patterns to avoid processing unnecessary files:

Automatic Exclusions

Agents automatically ignore:

• node_modules/ - Dependencies
• .git/ - Version control
• dist/, build/ - Build outputs
• .env files - Secrets
• IDE configurations
• OS-specific files

Custom Ignore Patterns

Create a .claude-ignore file in your project root:

# Example .claude-ignore
*.log
coverage/
temp/
secrets/

How It Works

• Agents read both .gitignore and .claude-ignore
• File searches automatically exclude ignored patterns
• Improves performance by skipping irrelevant files
• Prevents accidental exposure of sensitive data

🤝 Contributing

We love contributions! Here's how you can help:

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

Adding New Agents

1. Create agent structure:

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

2. Add slash command:

commands/
└── your-command.md

3. Submit PR with description

🐛 Troubleshooting

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

Common Issues

• Permission denied: Use sudo for global install
• Agent not found: Check spelling and installation
• Command not working: Ensure Claude Code is updated

📊 Release Notes

Version 1.0.0 (Latest)

• 🎉 Initial release
• 6 production-ready agents
• Interactive CLI interface
• Custom agent creation
• Project/user scope support
• Comprehensive documentation

📄 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

• Claude Code team at Anthropic
• Our amazing community of developers
• All contributors and testers
• Special thanks to webdevtodayjason for the original project

🔧 Development & Testing

Running Tests

# Run all tests
npm test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

Code Quality

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

Security

# Run security audit
npm audit

# Fix vulnerabilities
npm run audit:fix

See IMPROVEMENTS.md for detailed documentation on:

• 🧪 Testing framework setup
• 🔒 Security enhancements
• 📊 Type safety with JSDoc
• 🚀 CI/CD pipelines
• 📦 Dependency management

📬 Connect

• 🐛 Report Issues
• 💡 Request Features
• 🐦 Follow Updates
• ⭐ Star on GitHub

🔍 SEO Keywords & Use Cases

Perfect for developers who want to:

• Automate code reviews with AI-powered analysis
• Fix failing tests automatically using intelligent test runners
• Debug complex issues with expert error analysis
• Generate documentation from existing code
• Scan for security vulnerabilities proactively
• Refactor legacy code with modern patterns
• Enhance Claude Code with specialized capabilities
• Create custom AI agents for specific workflows

Technologies & Integrations:

• Works with Claude Code by Anthropic
• Supports all major programming languages
• Integrates with existing development workflows
• Compatible with Git, npm, yarn, and more
• Extensible through custom agent creation