An optimized AI-driven development framework that transforms Claude Code into a coordinated team of specialized agents with intelligent task orchestration, advanced MCP integration, and professional-grade quality.

HyperClaude Nano is an AI-driven development framework that turns Claude Code into an intelligent, coordinated team of specialist agents. Think of it as giving each developer their own personal development staff - with architects, coders, designers, security experts, testers, technical writers, and cloud engineers working together seamlessly.

• 7 Specialized Agents - Domain experts with specific tools and capabilities
• Wave Orchestration - Multi-phase execution for complex projects (W1→W2→W3→W4→W5)
• Reference-Based Communication - Agents share findings via structured protocols
• MCP-Powered Intelligence - 5 integrated servers providing superpowers

• Mandatory Task Tracking - TodoWrite enforced for 3+ step operations
• Pattern-Aware Analysis - Respects existing codebase conventions
• Parallel Execution - Multiple agents work simultaneously when possible
• Quality Gates - Built-in validation at every step
• Context Optimization - 40-50% token reduction via intelligent caching

Intelligent Routing: The framework analyzes your request and automatically selects the optimal agent(s) and execution strategy.

Wave Execution: For complex tasks, agents work in coordinated phases:

1. W1 (Architect) - System analysis and planning
2. W2 (Security) - Vulnerability assessment
3. W3 (Coder + Designer) - Parallel implementation
4. W4 (Test Engineer) - Quality validation
5. W5 (Tech Writer) - Documentation

Memory Persistence: All patterns, decisions, and findings are stored in the MCP memory server for cross-session intelligence.

Quality Assurance: Every operation goes through mandatory validation gates with evidence-based completion requirements.

• 7 Specialized Agents - Each with distinct tools, capabilities, and domain expertise
• Task Tool Integration - Agents coordinate via Claude Code's Task system
• Reference-Based Communication - Structured handoff protocols (see AGENT_PROTOCOLS.md)
• Memory Persistence - Shared knowledge via MCP memory server

• Mandatory TodoWrite - Enforced for operations with 3+ steps
• Status Tracking - pending → in_progress → completed with evidence requirements
• Quality Gates - Cannot mark complete without validation
• Progress Visibility - Real-time task status for users

• Trigger Conditions - >15 files, >5 types, >3 domains, or "comprehensive" requests
• Coordinated Phases - Sequential and parallel execution strategies
• Dependency Management - Smart ordering of agent activation
• Shared Context - Each wave builds on previous findings

The framework leverages 5 MCP servers for enhanced capabilities:

🧠 Memory Server - Cross-session pattern storage, agent communication, knowledge persistence 🔍 Tree-Sitter Server - AST analysis, code structure understanding, pattern detection 📚 Context7 Server - Live documentation lookup, framework best practices, library APIs 🌐 Puppeteer Server - Visual testing, screenshot generation, E2E automation 🧮 Sequential-Thinking Server - Complex problem decomposition, multi-step reasoning

Optimization Benefits:

• Token reduction via Memory caching
• Faster analysis via Tree-Sitter
• More efficient documentation lookup via Context7
• Parallel operation capabilities
• Structured data persistence

HyperClaude Nano requires 5 MCP servers for full functionality. Each server provides critical capabilities that enable the advanced agent coordination and analysis features.

Add these exact configurations to your ~/.claude.json file:

  "mcpServers": {
    "memory": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory@latest"],
      "env": {}
    },
    "puppeteer": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer@latest"],
      "env": {}
    },
    "context7": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"],
      "env": {}
    },
    "tree-sitter": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@nendo/tree-sitter-mcp@latest", "--mcp"],
      "env": {}
    },
    "sequential-thinking": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sequential-thinking@latest"
      ],
      "env": {}
    }
  },

Each agent is a domain specialist with specific tools, capabilities, and coordination protocols:

• Tools: Tree-Sitter, Memory, Context7, Sequential-Thinking
• Specialization: SOLID principles, design patterns, security analysis, architecture review
• Auto-triggers: /analyze, system-wide analysis, >15 files
• Mandatory Protocol: TodoWrite for multi-step analysis, reference-based handoffs
• Output: Structured findings (Template T2), pattern library, implementation plans
• Philosophy: Understand → Respect → Improve existing codebase patterns

• Tools: Task, Tree-Sitter, Context7, Memory
• Specialization: Feature implementation, bug fixes, pattern-consistent code generation
• Auto-triggers: /implement, /build, code modification requests
• Safety Features: Incremental changes, validation gates, test integration
• Coordination: Receives architect handoffs, works parallel with Designer
• Quality Assurance: Follows existing patterns, security-aware implementation

• Tools: Puppeteer, Context7, Tree-Sitter, Memory
• Specialization: Accessible components, responsive design, performance optimization
• Auto-triggers: /design, UI components, frontend patterns
• Visual Validation: Automated screenshots, cross-browser testing
• Coordination: Parallel execution with Coder, handoff to Test Engineer
• Quality Focus: Accessibility standards, performance metrics, design consistency

• Tools: Tree-Sitter, Memory, Sequential-Thinking, Context7
• Specialization: Code review for vulnerabilities, compliance validation, security patterns
• Auto-triggers: /security, Wave 2 execution, authentication/authorization code
• Analysis Depth: AST-based vulnerability detection, dependency scanning
• Communication: Security alert broadcasts, priority escalation protocols
• Focus Areas: Injection, auth/authz, data exposure, CORS/CSP, dependencies

• Tools: Puppeteer, Tree-Sitter, Memory, Task
• Specialization: Test creation, coverage analysis, E2E automation, quality validation
• Auto-triggers: /test, Wave 4 execution, quality assurance requests
• Testing Pyramid: Unit → Integration → E2E with intelligent test selection
• Automation: Browser testing, visual regression, interaction validation
• Metrics: Coverage tracking, quality gates, performance benchmarks

• Tools: Context7, Memory, Puppeteer, Tree-Sitter
• Specialization: API documentation, user guides, architecture documentation, doc sites
• Auto-triggers: /document, Wave 5 execution, documentation requests
• Frameworks: Nextra, Docusaurus, VitePress integration
• Content Sources: Receives implementation details from Coder/Designer agents
• Quality: Comprehensive coverage, visual examples, searchable documentation

• Tools: Context7, Memory, Sequential-Thinking, Tree-Sitter
• Specialization: Dynamic IaC language discovery, multi-provider expertise, cost optimization
• Auto-triggers: Infrastructure files (.tf, .yml, Dockerfile), deployment requests
• Capabilities: 20+ cloud providers, infrastructure patterns, deployment automation
• Analysis: Resource optimization, security compliance, scalability planning
• Integration: CI/CD pipelines, monitoring setup, disaster recovery

HyperClaude Nano provides 14 specialized commands that automatically route to appropriate agents with intelligent execution strategies:

# System Analysis & Architecture
/analyze [target] [--focus security|performance|quality]
  → Architect agent + Tree-Sitter analysis + Wave triggers

# Feature Implementation
/implement "feature description" [--type component|api|service]
  → Architect planning → Parallel(Coder, Designer) execution

# UI/UX Development
/design "component description" [--framework react|vue]
  → Designer agent + Puppeteer validation + accessibility checks

# Security Assessment
/security [target] [--depth quick|deep]
  → Security-Analyst + vulnerability scanning + compliance

# Quality Assurance
/test [target] [--type unit|integration|e2e]
  → Test-Engineer + automated test generation + coverage

# Documentation Generation
/document [target] [--framework nextra|docusaurus]
  → Tech-Writer + API extraction + visual examples

# Multi-Agent Workflows
/build [project] [--wave-mode]              # Full team coordination
/improve [target] [--focus performance]     # Architect + Coder optimization
/troubleshoot [issue] [--think]             # Architect + Sequential reasoning
/cleanup [codebase]                         # Coder + pattern optimization

# Specialized Operations
/task "complex request" [--agent-type]      # Custom agent assignment
/estimate "project scope"                   # Architect + Sequential planning
/workflow "process description"             # Process optimization

# Agent Selection
--agent-[type]          # Force specific agent type
--wave                  # Enable wave orchestration
--think                 # Add Sequential-Thinking analysis
--all-mcp              # Use all relevant MCP servers

# Scope & Focus
--scope file|module|project    # Analysis scope
--focus performance|security   # Specialized focus
--iterations[n]               # Iterative execution cycles

# Execution Modes
--safe                 # Conservative approach
--iterative           # Step-by-step validation
--parallel           # Enable parallel agent execution

Automatic Wave Triggers:

• >15 files in scope
• >5 component types detected
• >3 domains involved
• "comprehensive" in request

# Full Team Feature Development
/implement "e-commerce checkout system" --wave
# W1: Architect → system design
# W2: Security → payment security analysis
# W3: Coder + Designer → parallel implementation
# W4: Test-Engineer → validation & testing
# W5: Tech-Writer → documentation

# Comprehensive Code Improvement
/improve @enterprise-app/
# Auto-triggers wave mode due to size

# Security-First Development
/implement "payment processing" --focus security
# → Security analysis before implementation

# Performance-Critical Features
/design "real-time dashboard" --focus performance
# → Performance-aware UI patterns

# Enterprise Documentation
/document @api/ --framework nextra --comprehensive
# → Full documentation site with examples

# Legacy Code Modernization
/analyze @legacy-codebase/ --think-hard
# → Deep Sequential-Thinking analysis

• Claude Code (latest version)
• Node.js (for MCP servers)
• Git (for framework installation)

# 1. Install framework
cd ~/.claude
git init
git remote add origin https://github.com/rbonestell/claude-code.git
git fetch origin
git pull origin main

# 2. Add MCP configuration to ~/.claude.json
# (See MCP Server Configuration section above)

# 3. Restart Claude Code

Post-installation, you'll have:

• CLAUDE.md - Core configuration and rules
• AGENT_PROTOCOLS.md - Communication templates
• SHARED_PATTERNS.md - MCP optimization patterns
• commands/ - 14 specialized command definitions
• agents/ - 7 agent specifications with tools and capabilities

The framework uses multi-factor routing:

Command-Based Routing:

• /analyze → Architect (+ Tree-Sitter + Sequential-Thinking)
• /implement → Architect → Parallel(Coder, Designer)
• /security → Security-Analyst (+ Tree-Sitter + Sequential)
• /test → Test-Engineer (+ Puppeteer + Tree-Sitter)

Content Analysis:

• Security keywords → Security-Analyst activation
• UI/Component mentions → Designer integration
• Infrastructure files → Cloud-Engineer auto-trigger
• Complex logic → Sequential-Thinking enhancement

File Pattern Recognition:

• *.test.* → Test-Engineer priority
• *.jsx|tsx → Designer + Context7
• *.tf|*.yml → Cloud-Engineer
• package.json → Dependency analysis

Waves enable coordinated multi-agent execution with dependency management:

Wave Structure:

• W1 (Architect) - Analysis & Planning → Memory storage
• W2 (Security) - Vulnerability Assessment → Alert system
• W3 (Parallel) - Coder + Designer → Simultaneous implementation
• W4 (Test) - Validation & Quality → Gate enforcement
• W5 (Documentation) - Comprehensive docs → Knowledge capture

Coordination Mechanisms:

• Reference-based handoffs (Template T2, T3, T6)
• Shared memory keys (project:patterns:, review:findings:)
• Status synchronization (TodoWrite integration)
• Quality gates (validation before wave progression)

Structured Handoff Protocols:

{
  "handoff_type": "architect_to_coder",
  "patterns_ref": "project:patterns:arch-001",
  "findings_ref": "review:findings:arch-001",
  "execution_plan": {...}
}

Memory Key Conventions:

• project:patterns:* - Architectural patterns
• review:findings:* - Analysis results
• implementation:* - Code patterns
• security:findings:* - Vulnerability data
• test:coverage:* - Quality metrics

Communication Types:

• Sequential handoffs - Architect → Coder → Test
• Parallel coordination - Coder ↔ Designer sync
• Broadcast alerts - Security vulnerability notifications
• Status queries - Cross-agent progress checking

Mandatory Validation Gates:

• TodoWrite Enforcement - 3+ step operations require task tracking
• Evidence Requirements - Cannot mark complete without validation
• Pattern Consistency - Must respect existing codebase conventions
• Security Review - Automated vulnerability scanning
• Test Coverage - Quality metrics before completion

Context Optimization:

• 40% token reduction via Memory server caching
• Reference-based communication reduces redundancy
• Parallel execution improves throughput
• Incremental validation prevents compound errors

Mandatory Activation:

• Trigger: Operations with 3+ steps
• Enforcement: Framework blocks progression without TodoWrite
• States: pending → in_progress → completed
• Evidence: Completion requires validation proof

Task Structure:

{
  "content": "Analyze system architecture",
  "status": "in_progress",
  "activeForm": "Analyzing system architecture",
  "evidence": "file:line references, metrics",
  "agent": "architect"
}

Validation Requirements:

• Start Gate: Task setup verification
• Progress Gates: Incremental validation at each step
• Completion Gate: Evidence-based sign-off
• Handoff Gate: Structured agent transitions

Blocking Conditions:

• Incomplete validation
• Missing evidence
• Security vulnerabilities
• Test failures
• Pattern violations

# Full-Stack Feature Development
/implement "user authentication system" --wave
# W1: Architect → security analysis + patterns
# W2: Security → vulnerability assessment
# W3: Coder(backend) + Designer(frontend) → parallel
# W4: Test-Engineer → comprehensive testing
# W5: Tech-Writer → API + user documentation

# Legacy System Modernization
/analyze @legacy-codebase/ --think-hard --focus architecture
# Deep Sequential-Thinking analysis with architectural focus

# Security Compliance Audit
/security @production-api/ --depth deep --all-mcp
# Comprehensive security analysis with all MCP servers

# Performance-Critical Implementation
/implement "real-time analytics dashboard" --focus performance
# Performance-aware patterns + optimization

# Code Quality Improvement
/improve @codebase/ --iterations 3 --think
# Iterative improvement with Sequential-Thinking

# Documentation Site Generation
/document @api/ --framework nextra --comprehensive
# Full documentation site with examples and screenshots

"TodoWrite Required" Messages:

• Expected behavior for 3+ step operations
• Framework enforces task tracking for quality
• Let it proceed - creates automatic task management

MCP Server Failures:

• Fallback system maintains functionality
• Check ~/.claude.json configuration
• Verify Node.js installation for MCP servers

Agent Selection Issues:

• Use --agent-[type] to force specific agent
• Check command syntax against examples
• Framework auto-selects based on context analysis

Memory Server Benefits:

• Pattern caching across sessions
• 40% context reduction
• Cross-agent knowledge sharing

Parallel Execution:

• Wave 3 runs Coder + Designer simultaneously
• Use --parallel flag for multi-agent operations
• Tree-Sitter + Context7 can run concurrently

Custom Triggers:

• Modify trigger thresholds in CLAUDE.md
• Adjust wave activation conditions
• Configure MCP server priorities

Core Documentation:

• CLAUDE.md - System configuration, rules, MCP mappings
• AGENT_PROTOCOLS.md - Communication templates, memory keys
• SHARED_PATTERNS.md - MCP optimization strategies, performance patterns

Implementation Details:

• commands/ - 14 specialized command definitions with execution logic
• agents/ - 7 agent specifications with tools and capabilities
• README.md - This comprehensive guide

HyperClaude Nano is designed for extensibility:

• Custom agents can be added to the framework
• New commands follow established patterns
• MCP servers can be integrated following optimization patterns
• Communication protocols are versioned and backward-compatible

1. Start with auto-selection - let the framework choose agents
2. Use wave mode for complex multi-domain tasks
3. Leverage MCP caching - patterns persist across sessions
4. Trust the TodoWrite system - it ensures quality and completeness
5. Review agent handoffs - structured communication improves results

Optimization Achievements:

• 40% token reduction via Memory server caching
• 35% faster analysis via Tree-Sitter AST caching
• 50% lookup reduction via Context7 optimization
• 60% response time improvement via parallel execution
• 95% accuracy with quality gate enforcement

Framework Statistics:

• 7 specialized agents with distinct capabilities
• 14 command types with intelligent routing
• 5 MCP servers providing enhanced functionality
• 3-tier communication (sequential, parallel, broadcast)
• Reference-based protocols for efficient handoffs

License: MIT - Use and modify freely in your development workflow

Contributing:

• Framework is extensible by design
• Custom agents follow established patterns
• MCP optimization patterns documented in SHARED_PATTERNS.md
• Communication protocols versioned in AGENT_PROTOCOLS.md