⚡ Quick Install (30 Seconds) - No Shell Scripts!

Created: August 20, 2025
Lines of Code: 335,998+ in src/ folder alone
Test Coverage: 184 comprehensive tests

# Install with interactive prompts (secure & easy)
npm create agentwise@latest

# Or with yarn
yarn create agentwise

# Or with pnpm
pnpm create agentwise

✅ What Gets Installed

• 8 Specialized Agents working in parallel
• Global /monitor command accessible from anywhere
• Sandboxed execution - no --dangerously-skip-permissions needed
• Token optimization - 15-30% reduction through intelligent context sharing
• Real-time dashboard at http://localhost:3001

🎮 After Installation

# Create projects without any flags!
claude /create "a todo app with React"

# Monitor all agents in real-time
/monitor start

# Configure settings
claude /configure-agentwise

# Update to latest version (NEW!)
/update-agentwise

🔄 Updating Agentwise

NPM Update (Recommended):

# Run the installer again - it will detect and update existing installations
npm create agentwise@latest
# Choose "Update existing installation" when prompted

Manual Update (if preferred):

cd ~/agentwise
git pull origin main
npm install --legacy-peer-deps

📖 Complete Installation Guide | 🔧 Manual Installation

🎯 Overview

Agentwise is a comprehensive development platform that transforms project creation through intelligent automation. Built as an extension for Claude Code, it provides complete end-to-end project setup including requirements planning, database integration, GitHub configuration, and automated security protection.

Why Agentwise?

• 🚄 Parallel Execution: Multiple agents work simultaneously on different aspects of projects
• 🎭 Self-Improving Agents: Agents learn and improve from every task (VERIFIED ✅)
• 🔄 Smart Orchestration: Intelligent task distribution and phase management
• 📊 Real-time Monitoring: Track progress across all agents with live dashboard
• 🏗️ Smart Model Routing: Automatic model selection based on task type
• 💾 Context Management: Organized project context and task coordination
• 🖥️ Local Model Support: Ollama, LM Studio, and OpenRouter integration
• 🧠 Hybrid AI Strategy: Mix Claude, local models, and cloud APIs for optimal cost/performance
• 🔐 No --dangerously-skip-permissions Required: Sandboxed execution with automatic permission handling

🌟 Key Features

🔐 Sandboxed Execution (No --dangerously-skip-permissions Needed!)

Agentwise now operates without requiring the dangerous permissions flag:

Automatic Permission Handling

# Before: Required dangerous flag
claude --dangerously-skip-permissions /create my-app

# Now: Works without the flag!
claude /create my-app

How It Works

• Terminal Monitoring: Detects permission prompts automatically
• Smart Responses: Responds based on your configuration
• Workspace Sandboxing: Restricts execution to safe directories
• Safety Modes: Prevents dangerous operations in production

Configuration

/configure-agentwise              # Interactive setup wizard
/configure-agentwise permissions  # Configure permission handling
/configure-agentwise workspace    # Set sandbox boundaries

Enhanced Claude Code Capabilities

📄 Document Upload Support

Upload and process documents directly in Claude Code:

/upload requirements.pdf spec        # Convert PDF to project specs
/upload design-brief.docx context   # Use Word docs as project context
/upload technical-docs.pdf          # Process any document format

• Supported: PDF, Word, Text, Markdown, RTF
• Auto-extraction: Content, requirements, specifications
• Smart conversion: Documents → Project specs → Working code

🎨 Figma Dev Mode Integration

Direct integration with Figma Dev Mode MCP Server for seamless design-to-code:

/figma connect                      # Connect to Figma desktop
/figma generate Button              # Generate component from selection
/figma sync                         # Sync design tokens & components
/figma tokens ./tokens.json         # Export design variables
/figma image ./screenshot.png       # Capture design screenshots

• Real-time connection: Direct link to Figma desktop app
• Multi-framework: React, Vue, Angular, Swift, Kotlin support
• Design tokens: Auto-extract colors, typography, spacing
• Code Connect: Links Figma components to actual code
• Live sync: Changes in Figma instantly available

🖼️ Image Context Understanding

Enhanced image processing and visual context understanding:

/image                              # Visual file browser
/upload screenshot.png              # Process UI screenshots
/upload mockup.jpg                  # Convert mockups to code

• Visual understanding: Claude analyzes images properly
• Screenshot → Code: Build UIs from screenshots
• Mockup conversion: Turn designs into working apps
• Context awareness: Understands what's in the image

🌐 Website Cloning

Clone and customize websites with AI assistance:

/clone-website https://example.com exact     # 1:1 replica
/clone-website https://site.com similar      # Keep style, change brand

• Complete extraction: HTML, CSS, components, interactions
• Smart customization: Apply your branding automatically
• Component recognition: Identifies reusable patterns

Why These Features Matter

Before Agentwise:

• ❌ No way to upload documents to Claude Code
• ❌ Manual conversion of Figma designs
• ❌ Limited image understanding
• ❌ No website cloning capabilities

With Agentwise:

• ✅ Direct document processing in CLI
• ✅ Automatic Figma → Code conversion
• ✅ Full visual context understanding
• ✅ Website replication and customization

These features extend Claude Code's capabilities for more comprehensive development workflows.

🆕 Enhanced Context Management

Agentwise implements a dual-context system for better project organization:

📋 AGENTS.md (Context 2.0)

Based on OpenAI's AGENTS.md specification, this provides a universal interface for AI tools:

• Universal Compatibility: Any AI CLI can understand your project
• Human-Readable: Clear guidance for both humans and AI
• Standardized Format: Following OpenAI's open specification
• Project Guidelines: Setup, testing, architecture, conventions

🧠 CodebaseContextManager (Context 3.0)

Our proprietary real-time context awareness system:

• Dynamic Understanding: Tracks your entire codebase
• Real-Time Updates: File changes tracked automatically
• Deep Analysis: Extracts imports, exports, classes, functions
• Smart Updates: Only refreshes changed portions
• Hierarchical Understanding: Maintains project structure relationships

How They Work Together

AGENTS.md → Universal AI Interface (any tool can read)
     +
CodebaseContextManager → Deep, Real-Time Understanding (Agentwise exclusive)
     =
Comprehensive Context System: Universal compatibility + deep awareness

Note: Our approach combines universal compatibility (AGENTS.md) with real-time codebase understanding, making it particularly well-suited for multi-agent workflows.

✨ Features

Core Capabilities

💎 What Makes Agentwise Special

Agentwise addresses Claude Code limitations and extends its capabilities:

🎯 Problems We Solve

🎯 Key Achievements

• File upload support for Claude Code workflows
• Figma design file integration and processing
• Project context management and intelligent task distribution
• Comprehensive MCP integration with 25 verified servers
• Website cloning and customization capabilities
• Modern documentation with responsive design
• Context 3.0: Measured 15-30% token reduction with multi-agent orchestration

📊 Token Optimization Visualization

How Agentwise Optimization Works

Note: Optimization benefits only apply to multi-agent scenarios. Single agents see no benefit or may use slightly more tokens due to overhead.

graph TB
    subgraph "❌ Without Agentwise"
        A1[Single User/Agent<br/>10,000 tokens]
        A1 -->|Full Context| API1[Claude API<br/>💰 $0.15]
        
        B1[5 Agents Traditional<br/>50,000 tokens]
        B1 -->|5x Full Context| API2[Claude API<br/>💰 $0.75]
        
        C1[10 Agents Traditional<br/>100,000 tokens]
        C1 -->|10x Full Context| API3[Claude API<br/>💰 $1.50]
    end
    
    subgraph "✅ With Agentwise Optimization"
        D1[Single User<br/>10,000 tokens]
        D1 -->|No benefit| API4[Claude API<br/>💰 $0.15]
        
        E1[5 Agents Optimized<br/>42,500 tokens]
        E1 -->|Shared Context| SC1[Context<br/>Server]
        SC1 -->|15% less| API5[Claude API<br/>💰 $0.64]
        
        F1[10 Agents Optimized<br/>77,000 tokens]
        F1 -->|Shared Context| SC2[Context<br/>Server]
        SC2 -->|23% less| API6[Claude API<br/>💰 $1.16]
    end
    
    style A1 fill:#ff6b6b,color:#fff
    style B1 fill:#ff6b6b,color:#fff
    style C1 fill:#ff6b6b,color:#fff
    style D1 fill:#ffd93d,color:#000
    style E1 fill:#6bcf7f,color:#fff
    style F1 fill:#6bcf7f,color:#fff
    style SC1 fill:#4dabf7,color:#fff
    style SC2 fill:#4dabf7,color:#fff

🏆 Realistic Performance Metrics

Token Usage Comparison (Empirical Data)

All results verified through comprehensive testing - see test files for details

How Token Optimization Works

sequenceDiagram
    participant PM as Project Manager
    participant CS as Context Server<br/>(Port 3003)
    participant A1 as Frontend Agent
    participant A2 as Backend Agent
    participant A3 as Database Agent
    participant API as Claude API
    
    Note over PM,API: 🚀 Initial Setup (One-time)
    PM->>CS: Upload full project context (1,344 bytes)
    CS->>CS: Store and version context
    CS-->>PM: Context ID: project-123
    
    Note over PM,API: 👥 Agent Execution (Optimized)
    A1->>CS: Get context reference
    CS-->>A1: Context hash + ref (50 bytes)
    A1->>API: Task + context ref (250 bytes total)
    
    A2->>CS: Get context reference
    CS-->>A2: Context hash + ref (50 bytes)
    A2->>API: Task + context ref (250 bytes total)
    
    A3->>CS: Get context reference
    CS-->>A3: Context hash + ref (50 bytes)
    A3->>API: Task + context ref (250 bytes total)
    
    Note over PM,API: 🔄 Updates (Differential Only)
    A1->>CS: Send changes only (50 bytes)
    CS->>A2: Broadcast diff
    CS->>A3: Broadcast diff
    
    Note over PM,API: ✅ Total: 5,460 bytes vs 8,400 bytes
    Note over PM,API: 💰 Saved: 2,940 tokens (35% reduction)

🚀 Quick Start

Prerequisites

• Node.js 18.0 or higher
• Claude Code CLI installed
• Git for version control
• macOS/Linux or Windows with WSL

✅ Note: Agentwise now works without requiring the --dangerously-skip-permissions flag through automatic permission handling and sandboxed execution.

Installation

NPM Installation (Recommended)

Secure installation without shell scripts:

# Interactive installer - works on all platforms
npm create agentwise@latest

# Alternative package managers
yarn create agentwise
pnpm create agentwise

What you get:

• Secure, transparent installation process
• Choice of installation location
• Automatic existing installation detection
• Cross-platform compatibility
• No shell scripts or security concerns

🔧 Manual Installation

For advanced users who prefer manual setup:

# 1. Clone the repository
git clone https://github.com/VibeCodingWithPhil/agentwise.git
cd ~/agentwise

# 2. Install dependencies
npm install

# 3. Build the project
npm run build

# 4. Create workspace directory
mkdir -p workspace

# 5. Install global monitor command
npm run monitor:install

# 6. Start Agentwise
node dist/index.js

# 7. In a new terminal, test without any flags!
claude /create "your first project"

🎯 Configure Sandboxed Execution (Optional)

Remove the need for --dangerously-skip-permissions:

# Run the configuration wizard
claude /configure-agentwise

# Or create config file directly at ~/.agentwise-config.json
{
  "permissions": {
    "bypassEnabled": true,
    "safetyMode": "moderate",
    "autoResponse": true
  },
  "workspace": {
    "enableSandbox": true,
    "restrictPaths": true,
    "allowedPaths": ["~/agentwise/workspace"]
  }
}

Benefits of Manual Installation:

• Full control over configuration
• Customize installation location
• Modify source code directly
• Integrate with existing workflows

📦 Complete Command Reference (45 Commands)

Agentwise provides 45 powerful commands organized by category:

📦 Project Creation & Management (11 commands)

/create <idea>                   # Create project with smart agent selection
/create-plan <idea>              # Collaborative planning mode
/create-project <idea>           # Complete setup wizard with all features
/projects                        # List and select active projects
/project-status                  # View current project status
/task <feature>                  # Add features to active project
/task-dynamic <feature>          # Dynamic task distribution
/task-plan <feature>             # Plan tasks before execution
/task-import <source>            # Import tasks from external sources
/init-import                     # Import external project
/clone-website <url>             # Clone and customize websites

📋 Requirements & Planning (4 commands)

/requirements <idea>             # Generate project requirements
/requirements-enhance            # Enhance existing requirements
/requirements-visualize          # Create visual HTML specifications
/requirements-to-tasks           # Convert requirements to tasks

🗄️ Database Integration (3 commands)

/database-wizard                 # Interactive database setup wizard
/database-setup                  # Quick database configuration
/database-connect                # Connect to existing database

🔐 Security & Protection (5 commands)

/enable-protection               # Enable automated backup and security
/protection-status               # View real-time protection status
/security-review                 # Comprehensive security analysis
/security-report                 # Generate detailed security report
/rollback                        # Rollback to previous safe state

🎨 Figma Integration (8 commands)

/figma                          # Main Figma integration menu
/figma-auth                     # Authenticate with Figma
/figma-list                     # List available Figma files
/figma-select                   # Select Figma file
/figma-inspect                  # Inspect Figma components
/figma-generate                 # Generate code from designs
/figma-sync                     # Sync changes with Figma
/figma-create                   # Create new Figma components

🤖 Model & Agent Management (6 commands)

/generate-agent <spec>          # Create custom specialized agents
/setup-ollama                   # Install and configure Ollama
/setup-lmstudio                 # Configure LM Studio
/local-models                   # List available local models
/configure-routing              # Configure smart model routing
/setup-mcps                     # Configure 25 MCP servers

📊 Monitoring & Analysis (3 commands)

/monitor                        # Launch real-time dashboard
/visual-test                    # Run visual regression tests
/docs                          # Open documentation hub

🛠️ Configuration & Tools (3 commands)

/configure-agentwise           # Configure settings
/upload <file>                 # Upload documents (PDF, Word, Figma)
/image                         # Visual context file browser

🚀 Deployment & Updates (2 commands)

/deploy                        # Deploy project to production
/update-agentwise              # Update to latest version

📚 View Complete Commands Documentation for detailed usage and examples

First Project

# Create a new project directly
/create "an e-commerce platform with Next.js and Stripe"

# Monitor progress in real-time
/monitor

# Add features to active project
/task "add user authentication with OAuth"

📚 Documentation

📊 Real-Time Monitoring Dashboard with Observable Visualizations

Agentwise includes a comprehensive web-based monitoring dashboard that provides real-time visibility into your agent orchestration:

Features

• Live Agent Status: Real-time progress tracking for all active agents
• Task Feed: Live stream of task completions and updates
• Interactive Controls: Pause, resume, or manage individual agents
• Progress Visualization: Progress bars, completion percentages, and timelines
• System Health: CPU, memory, and network monitoring
• Multi-Project Support: Automatic project detection and switching
• Observable Plot Charts: Professional data visualizations with D3.js
• Knowledge Graph Visualization: Interactive codebase structure exploration
• Token Optimization Metrics: Real-time charts showing 15-30% reduction

Starting the Monitor

/monitor                    # Opens dashboard (auto-installs global command)
/monitor install            # Manually install global command
/monitor global             # Alternative install command  
/monitor status             # Check installation status
/monitor help               # Show monitor command help

Note: Running /monitor without subcommands now automatically installs the global command if not present