SetupAI

The Ultimate CLI for AI-Powered Development Workflows with Claude

SetupAI automatically analyzes your project's tech stack and generates comprehensive configuration files, skills, agents, git hooks, and enforcement scripts to supercharge your development workflow with Claude Code.

What's New in v1.8.1

CLI Cleanup:

• Removed init command - Redundant wrapper, use setupai analyze directly
• Removed skills add/agents add - Unimplemented commands removed
• Dynamic counts - skills list and agents list now show accurate counts from detector

What's New in v1.8.0

Feature-Aware Audit Mode:

• Automatic Feature Detection - setupai audit now detects features in your codebase even without BLUEPRINT.md
• 50+ Feature-Specific Rules - Checks tailored to detected features (Auth, Payment, File Upload, Real-time, API, etc.)
• Dual Report Generation - Creates both BEST_PRACTICES_REPORT.md and FEATURE_AUDIT_REPORT.md
• Smart Recommendations - Context-aware suggestions based on what features you're actually using

Feature-Specific Checks Include:

• Authentication (AUTH): Password hashing, JWT/session libraries, CSRF protection, auth tests
• Payments (PAY): Webhook verification, idempotency keys, audit logging, subscription hooks
• File Upload (FILE): File type validation, size limits, virus scanning, CDN recommendations
• Real-time (RT): WebSocket authentication, message rate limiting, reconnection handling
• API (API): Versioning, request validation, error standardization, pagination
• Database (DB): Migrations, seeding, soft delete patterns
• Background Jobs (JOB): Retry logic, monitoring, dead letter queues
• And more: Caching, Email, Search rules

New Files:

• src/utils/feature-audit-rules.js - Centralized feature rule definitions
• .claude/context/FEATURE_AUDIT_REPORT.md - Feature-specific audit report

What's New in v1.7.0

Command Consolidation:

• Streamlined CLI - Removed redundant commands for cleaner experience
• Removed update - Use setupai analyze --merge instead (adds missing skills/agents without overwriting)
• Removed clean - Use setupai cleanup for full uninstall
• Removed legacy syntax - Use skills list instead of list skills
• Blueprint --scan enhancement - Now automatically runs understand first for complete analysis

What's New in v1.6.0

Best Practices Audit Mode:

• Automatic Mode Detection - setupai audit now auto-runs best practices mode when no BLUEPRINT.md exists
• 6 Audit Categories - Security, Performance, Code Quality, Testing, Documentation, Configuration
• 40+ Best Practice Rules - Comprehensive checks based on detected tech stack
• Auto-Fix Support - Many issues can be fixed automatically with --fix commands
• Severity Levels - Critical, High, Medium, Low prioritization
• Tech-Stack Aware - Checks are tailored to your framework (Next.js, Express, Django, etc.)

New Audit Commands:

• setupai audit - Auto-detects mode (best practices if no BLUEPRINT, feature audit if BLUEPRINT exists)
• setupai audit --best-practices - Force best practices mode even with BLUEPRINT.md
• setupai audit --fix=SEC-001 - Fix a specific issue by ID
• setupai audit --fix-category=security - Fix all issues in a category
• setupai audit --fix-all - Fix all auto-fixable issues

Best Practices Checks Include:

• Security: .env exposure, missing helmet.js, rate limiting, hardcoded secrets, input validation
• Performance: Image optimization, code splitting, bundle size, N+1 queries
• Code Quality: TypeScript setup, ESLint, Prettier, pre-commit hooks
• Testing: Test framework, coverage, E2E tests
• Documentation: README, .env.example, API docs
• Configuration: .gitignore, CI/CD, .editorconfig

What's New in v1.5.0

Agent System Overhaul:

• Output Schemas - 18 agents now have structured output schemas for consistent responses
• Guardrails - Input validation, output filtering, and behavior constraints for safety
• Tool Definitions - 16 agents have defined tools (analyze, generate, check, etc.)
• Agent Router - Intelligent routing based on request content with confidence scores
• Agent Metrics - Track agent performance, usage patterns, and success rates
• Workflow Templates - 8 pre-built workflows (feature-impl, bug-fix, code-review, etc.)
• Session Context - Memory persistence across agent interactions
• Enhanced Experts - Go, Rust, and MCP agents upgraded with comprehensive examples

New Commands:

• setupai agents stats - View agent performance dashboard
• setupai agents info <name> - Get detailed agent information
• setupai agents route "<message>" - Test which agent handles a request

What's New in v1.4.1

CLI Restructuring & Cleanup:

• Simplified understand command - Always does deep scan (removed --quick and --full flags)
• New skills and agents subcommands - setupai skills list, setupai skills remove <name>, setupai agents remove <name>
• Conditional VSCode config - Only generates .vscode/ files if directory already exists
• Simplified clean command - Cleans everything by default (removed granular flags)
• Removed wasteful flags - --complete, --skip-vscode, granular clean flags

What's New in v1.4.0

Codebase Cleanup & Optimization:

• Removed Screenshot Capture - No longer auto-starts dev servers or captures screenshots
• Removed Playwright Auto-Install - Won't automatically install Playwright browsers
• Removed Database Introspection - Simplified codebase (removed fragile pattern-based schema detection)
• Consolidated Utilities - Colors and prompts now use shared modules (utils/logger.js, utils/prompt.js)
• Fixed Bugs - Fixed prompt.confirm() bug in blueprint command
• Cleaner Output - Removed DB_SCHEMA.md generation from understand command

What's New in v1.3.0

• Blueprint Auto-Scan - setupai blueprint --scan auto-detects existing features from your codebase
• Project Type Detection - Identifies admin panels, SaaS, APIs, CLIs, and adapts questions accordingly
• Context-Aware Questions - Asks relevant questions based on project type (skips user-role questions for admin-only tools)
• Current vs Vision Tracking - Documents what EXISTS vs what you WANT for each feature
• Implementation Preferences - Captures how features should work (hardcoded vs admin-configurable, etc.)
• Gap Analysis - Automatically identifies what's implemented, partial, or planned

What's New in v1.2.0

• Cleanup Command - setupai cleanup removes ALL SetupAI files (full uninstall/reset)
• Manifest Tracking - INSTALL_MANIFEST.json tracks all created files for reliable cleanup
• Dry Run Support - Preview cleanup with --dry-run before deleting
• Safe Defaults - Requires --force flag to actually delete files

Features

• Smart Detection - Automatically detects 8 languages, 107 skills, and 27 agents
• Monorepo Support - Detects npm/yarn/pnpm workspaces, Lerna, Nx, Turborepo, Rush
• Config Generation - Creates CLAUDE.md, AI_RULES.md, and context files
• Skills Library - 107 tech-specific skill templates (TypeScript, React, Python, Go, etc.)
• Agent System - 27 specialized agents with output schemas, guardrails, and tool definitions
• Agent Router - Intelligent routing that suggests the best agent for your task
• Session Context - Memory persistence across agent interactions (survives compaction)
• Git Hooks - Pre-commit, commit-msg, pre-push hooks with language-specific checks
• Enforcement Scripts - 16 scripts including 7-level verification pipeline
• Feature Templates - 8 ready-to-use templates (auth, crud, users, payments, etc.)
• Blueprint System - Auto-detect existing features or manually define project vision

Installation

# Install globally
npm install -g setupai

# Or use with npx
npx setupai analyze

Quick Start

# Navigate to your project
cd your-project

# Run SetupAI
setupai analyze

# That's it! Start using Claude Code with your new configuration

Commands

Core Setup Commands

| Command | Description | |---------|-------------| | setupai analyze | Main command - Detects tech stack, generates CLAUDE.md, AI_RULES.md, skills, agents, hooks | | setupai analyze --merge | Preserves existing custom rules and adds missing skills/agents without overwriting | | setupai doctor | Health check - verifies all SetupAI files are properly installed |

Understanding Your Codebase

| Command | Description | |---------|-------------| | setupai understand | Deep analysis - generates PROJECT_MAP.md (structure), PATTERNS.md (code patterns), API_MAP.md (endpoints) |

Blueprint (Project Planning)

| Command | Description | |---------|-------------| | setupai blueprint | Manual mode - Interactive wizard where YOU enter project goals, features, constraints | | setupai blueprint --scan | Auto-detect mode - Runs understand first, then scans for features, asks context-aware questions | | setupai blueprint --migrate | Migrate mode - Move root BLUEPRINT.md to .claude/context/ (recommended location) |

Note: blueprint --scan automatically runs understand first to generate context files, then detects features.

Audit (Feature Verification & Best Practices)

| Command | Description | |---------|-------------| | setupai audit | Smart mode - Runs best practices audit if no BLUEPRINT.md, otherwise compares features vs implementation | | setupai audit --best-practices | Force best practices mode (checks security, performance, code quality, etc.) | | setupai audit --fix=SEC-001 | Fix a specific issue by ID | | setupai audit --fix-category=security | Fix all issues in a category (security, performance, testing, etc.) | | setupai audit --fix-all | Fix all auto-fixable issues | | setupai audit --status | Show current audit progress | | setupai audit --next | Process next pending feature | | setupai audit --approve | Approve suggestions for implementation | | setupai audit --verify | Run verification pipeline | | setupai audit --commit | Create AUDIT_APPROVED.md for commit | | setupai audit --stop | Exit audit mode |

Skills & Agents

| Command | Description | |---------|-------------| | setupai skills list | List all available skills (auto-detects count) | | setupai skills remove <name> | Remove a skill | | setupai agents list | List all available agents (auto-detects count) | | setupai agents remove <name> | Remove an agent | | setupai agents stats | View agent performance metrics dashboard | | setupai agents info <name> | Get detailed info about a specific agent | | setupai agents route "<msg>" | Test agent routing for a message |

Cleanup

| Command | Description | |---------|-------------| | setupai cleanup | Remove ALL SetupAI files (full uninstall/reset) | | setupai cleanup --dry-run | Preview which SetupAI files would be removed | | setupai cleanup --force | Remove without confirmation prompt |

Options

| Flag | Description | |------|-------------| | --help, -h | Show help message | | --version, -v | Show version | | --dry-run | Preview changes without writing files | | --force | Overwrite existing files / confirm cleanup deletion | | --merge | Merge with existing AI rules (preserves your custom rules) | | --skip-hooks | Skip git hooks installation | | --scan | Auto-detect existing features (for setupai blueprint only) | | --migrate | Migrate root BLUEPRINT.md to .claude/context/ (for setupai blueprint only) | | --stop | Exit audit mode (for audit command) | | --status | Show audit progress (for audit command) | | --next | Process next feature (for audit command) | | --approve | Record user approval (for audit command) | | --verify | Run verification (for audit command) | | --commit | Create commit approval (for audit command) | | --best-practices, -bp | Force best practices audit mode (for audit command) | | --fix=ID | Fix specific issue by ID, e.g., --fix=SEC-001 (for audit command) | | --fix-category=CAT | Fix all issues in category (for audit command) | | --fix-all | Fix all auto-fixable issues (for audit command) |

What Gets Generated

your-project/
├── CLAUDE.md                     # Main AI workflow instructions
├── AI_RULES.md                   # Project-specific coding standards
├── GETTING_STARTED.md            # Actionable next steps guide (delete after reading)
└── .claude/
    ├── settings.json             # Claude Code settings & hooks
    ├── skills/                   # 20-40 relevant skills (from 107)
    │   ├── INDEX.md
    │   ├── typescript.md
    │   ├── react.md
    │   └── ...
    ├── agents/                   # 8-15 relevant agents (from 26)
    │   ├── INDEX.md
    │   ├── planner.md
    │   ├── debugger.md
    │   └── ...
    ├── features/                 # 8 feature templates
    │   ├── auth/
    │   ├── crud/
    │   ├── users/
    │   ├── payment/
    │   └── ...
    └── context/                  # Project context files
        ├── PROJECT_MAP.md        # Directory structure
        ├── PATTERNS.md           # Code patterns detected
        ├── API_MAP.md            # API endpoints
        ├── BLUEPRINT.md          # Project vision & features
        └── ...

Scripts generated in scripts/:

• verify-pipeline.js - 7-level verification
• context-loader.js - Session initialization with agent awareness
• update-context.js - Context sync with agent reminders on compaction
• checkpoint.js - Save/restore state
• scope-check.js - Commit scope validation
• enforce-feature-plan.js - Feature tracking
• And 10 more enforcement scripts

Supported Technologies

Languages (8)

• JavaScript / TypeScript
• Python
• Go
• Rust
• Java
• C# / .NET
• PHP

Frameworks & Libraries

• Frontend: React, Vue, Angular, Svelte, Next.js, Nuxt, Remix, Astro
• Backend: Express, Fastify, NestJS, FastAPI, Django, Flask, Gin, Fiber, Spring Boot
• API Styles: REST, GraphQL, tRPC
• Database: PostgreSQL, MySQL, MongoDB, SQLite, Redis
• ORM: Prisma, TypeORM, Drizzle, Mongoose, Sequelize, SQLAlchemy, Django ORM, GORM, Eloquent
• Testing: Jest, Vitest, Pytest, Go test, Playwright, Cypress
• Styling: Tailwind CSS, CSS Modules, Styled Components, Sass
• Monorepo: npm/yarn workspaces, pnpm workspaces, Lerna, Nx, Turborepo, Rush

Example Workflows

New Project Setup

mkdir my-app && cd my-app
npm init -y
npm install next react react-dom
setupai analyze

Existing Project

cd existing-project
setupai analyze       # Auto-detect and setup
setupai understand    # Deep codebase analysis
setupai doctor        # Verify setup

Existing Project - Auto-Detect Features

cd existing-project

# Auto-scan codebase to detect existing features
setupai blueprint --scan

# What happens:
# 1. Detects project type (Admin Panel, SaaS, API, CLI, etc.)
# 2. Scans codebase for features (auth, payments, CRUD, etc.)
# 3. Shows each detected feature with files/endpoints found
# 4. Asks context-aware questions (e.g., "Are roles hardcoded or dynamic?")
# 5. Generates BLUEPRINT.md with current state + your vision

# Then run audit to verify implementation matches vision
setupai audit

Example Output:

╔═══════════════════════════════════════════════════════════╗
║  User Authentication                                       ║
╠═══════════════════════════════════════════════════════════╣
║  Type: User login, logout, session management              ║
║  Files: src/auth/login.ts, middleware/auth.ts              ║
║  Endpoints: /api/auth/login, /api/auth/logout              ║
║  Status: ✅ Has tests                                      ║
╚═══════════════════════════════════════════════════════════╝
? Action: Keep / Edit name / Skip
? Vision for User Authentication: Support OAuth + magic links

Existing Project with AI Rules

cd existing-project

# Merge SetupAI config with your existing rules (recommended)
setupai analyze --merge

# Your custom rules are preserved and appended
# Backups created: CLAUDE.md.backup, AI_RULES.md.backup

Team Onboarding

# Generate comprehensive documentation
setupai understand
setupai blueprint

Quick Code Quality Check

cd your-project

# Run best practices audit (no setup required!)
setupai audit

# Fix all auto-fixable issues
setupai audit --fix-all

# Or fix by category
setupai audit --fix-category=security
setupai audit --fix-category=code-quality

Cleanup / Uninstall

# Preview what would be removed
setupai cleanup --dry-run

# Remove ALL SetupAI files from your project
setupai cleanup --force

Agent Routing

SetupAI v1.5.0 introduces intelligent agent routing that helps you find the right agent for any task.

How It Works

# Test which agent handles your request
setupai agents route "I need to fix a bug in the login form"
# Output:
#   Primary: debugger
#   Confidence: 85%
#   Supporting: frontend-engineer, security-expert

setupai agents route "Review my pull request"
# Output:
#   Primary: reviewer
#   Confidence: 92%
#   Supporting: security-expert

Session Context

The context-loader runs automatically on session start and displays:

• Installed agents with their trigger keywords
• Suggested agent based on your current task
• Context files loaded for the session

After context compaction, agent reminders are displayed to ensure Claude doesn't forget which agents are available.

Available Workflows

The router detects these workflow patterns and suggests agent sequences:

| Workflow | Agents | |----------|--------| | feature-implementation | planner → engineer → tester → reviewer | | bug-fix | debugger → tester → reviewer | | code-review | reviewer → security-expert → performance-expert | | security-audit | security-expert → reviewer → documenter | | performance-optimization | performance-expert → database-engineer → tester | | documentation | documenter → api-designer → reviewer |

Audit Mode

The audit command has two modes that activate automatically:

Best Practices Mode (No BLUEPRINT.md)

When no BLUEPRINT.md exists, setupai audit automatically runs best practices analysis:

# Runs best practices audit (auto-detects when no BLUEPRINT.md)
setupai audit

# Force best practices mode even with BLUEPRINT.md
setupai audit --best-practices

Output Example:

═══════════════════════════════════════════════════════════
        BEST PRACTICES AUDIT REPORT
═══════════════════════════════════════════════════════════

Total Issues: 12
🔴 Critical: 1   🟠 High: 3   🟡 Medium: 5   🟢 Low: 3

Report saved to: .claude/context/BEST_PRACTICES_REPORT.md

═══════════════════════════════════════════════════════════
           AUTO-FIXABLE ISSUES
═══════════════════════════════════════════════════════════

  [SEC-001] 🔴 Environment file may be exposed
         → echo ".env" >> .gitignore
  [CQ-003] 🟡 ESLint not configured
         → npm init @eslint/config@latest
  ...

Fix Issues:

# Fix a specific issue
setupai audit --fix=SEC-001

# Fix all security issues
setupai audit --fix-category=security

# Fix all auto-fixable issues
setupai audit --fix-all

Categories Checked: | Category | Examples | |----------|----------| | 🔒 Security | .env exposure, missing helmet, rate limiting, hardcoded secrets | | ⚡ Performance | Image optimization, bundle size, code splitting | | 📝 Code Quality | TypeScript, ESLint, Prettier, pre-commit hooks | | 🧪 Testing | Test framework, coverage, E2E tests | | 📚 Documentation | README, .env.example, API docs | | ⚙️ Configuration | .gitignore, CI/CD, .editorconfig |

Feature Audit Mode (With BLUEPRINT.md)

When BLUEPRINT.md exists, the audit compares your planned features against actual implementation:

# Start feature audit
setupai audit

# Check audit progress
setupai audit --status

# Process next pending feature
setupai audit --next

# Exit audit mode
setupai audit --stop

How it works:

1. Auto-Parse BLUEPRINT - Extracts all features from .claude/context/BLUEPRINT.md
2. Auto-Scan Codebase - Finds implementations for each feature (files, API, UI, tests)
3. Auto-Generate Report - Creates .claude/context/AUDIT_REPORT.md with feature-by-feature analysis
4. Approve - You review report and approve which suggestions to implement
5. Implement - Claude implements with full agent workflow
6. Verify - Runs 7-level verification
7. Commit - Only allowed after AUDIT_APPROVED.md is created

Feature Status in Report: | Status | Meaning | |--------|---------| | ✅ Complete | Feature found with API, UI, and tests | | ⚠️ Partial | Feature exists but missing components | | ❌ Missing | Feature in BLUEPRINT but not implemented |

Enforcement:

• Git pre-commit hook blocks commits without AUDIT_APPROVED.md
• Phase checkpoints prevent skipping steps

Scripts

Verification Pipeline

# Run full 7-level verification
node scripts/verify-pipeline.js

# Quick check (levels 1-3)
node scripts/verify-pipeline.js --quick

Levels:

1. Static Analysis (type check, lint)
2. Build
3. Unit Tests
4. API Tests
5. Integration Tests
6. Coverage
7. Security/Accessibility

Checkpoint System

# Save current state
node scripts/checkpoint.js save "before-refactor"

# Restore to checkpoint
node scripts/checkpoint.js restore "before-refactor"

Requirements

• Node.js 18+
• Git (for hooks installation)

License

MIT - see LICENSE for details.

Built with care for developers who want AI-powered development workflows.