PackAI

A VS Code extension that intelligently coordinates Claude, Copilot, and Codex agents to build web projects faster. Instead of switching between AI tools, PackAI analyzes your project, creates an execution plan, and assigns each task to the best agent automatically.

What It Does

1. You describe a project (e.g., "Build an e-commerce store with Stripe payments")
2. PackAI analyzes your intent and detects project type, features, and complexity
3. It generates an execution plan with phased tasks and dependency ordering
4. Each task is assigned to the optimal agent based on task characteristics:
   • Claude -- architecture, database schemas, complex logic
   • Copilot -- boilerplate, UI components, quick edits
   • Codex -- background tasks, bulk operations, test generation
5. A live dashboard tracks progress, shows conflicts, and lets you pause/resume

Prerequisites

• VS Code 1.109 or later
• Node.js 20+
• GitHub Copilot subscription (for language model access)

Installation

From Source (Development)

git clone https://github.com/your-org/packai.git
cd packai
npm install
npm run compile

Then press F5 in VS Code to launch the Extension Development Host.

From VSIX (Pre-built)

npm run package    # creates .vsix file
code --install-extension packai-0.1.0.vsix

Quick Start

1. Open a workspace in VS Code (File > Open Folder)
2. Start a project via Command Palette: Ctrl+Shift+P > "PackAI: Start Project"
3. Pick a project type (E-commerce, Landing Page, Dashboard, Blog, or Custom)
4. View the execution plan in the dashboard panel
5. Use chat for details: type @packai /scaffold Build an online store with Stripe in the Chat panel

Features

Intelligent Intent Analysis

PackAI parses natural language descriptions and extracts:

• Project type (e-commerce, landing, dashboard, blog, etc.)
• Features (auth, payments, real-time, search, etc.)
• Stack hints (React, Next.js, PostgreSQL, etc.)
• Complexity level (simple, moderate, complex, enterprise)

Workflow Templates

5 built-in templates with pre-configured task dependencies:

You can also create, import, and export custom templates.

Smart Agent Selection

The AgentSelector scores each task against agent capabilities using:

• Task category signals (architecture, UI, testing, etc.)
• Complexity and parallelizability
• Historical benchmark data (when available)
• User preference settings (strategy, cost level)

Live Dashboard

A webview panel showing:

• Phase progress with task status indicators
• Per-agent stats (tasks completed, failed, in progress)
• Activity log with timestamped events
• Conflict detection and resolution UI

Orchestration Controls

Manage running sessions from the Command Palette or dashboard:

• Pause / Resume / Cancel all sessions
• View individual session details
• Retry failed tasks
• Resolve conflicts between agent outputs

Quality Gates

Every agent output is validated through 4 gates:

Error Recovery

• Agent fallback: if Claude fails, automatically tries Copilot, then Codex
• Rate limit queue: queues requests when API limits are hit
• State checkpoints: auto-saves plan state for crash recovery
• Typed error hierarchy: every error has a code, user message, and stack trace

Command Palette

All commands are under the "PackAI" category:

Chat Commands

Configuration

All settings are under the packai.* namespace in VS Code settings:

See docs/user-guide.md for the full settings reference.

Project Structure

vsex/
├── src/
│   ├── commands/           # Command palette integrations
│   │   ├── index.ts        # registerAllCommands + CommandDeps
│   │   ├── startProject.ts # Project creation wizard
│   │   ├── manageOrchestration.ts  # Pause/resume/cancel
│   │   ├── templates.ts    # Template CRUD
│   │   └── settings.ts     # Quick-pick settings
│   ├── intelligence/       # NLP + planning (no vscode imports)
│   │   ├── intentAnalyzer.ts       # Natural language → ProjectIntent
│   │   ├── workflowGenerator.ts    # Intent → ExecutionPlan
│   │   ├── workflowTemplates.ts    # Template registry (5 built-in)
│   │   ├── agentSelector.ts        # Task → AgentRecommendation
│   │   └── types.ts
│   ├── orchestration/      # Session management + coordination
│   │   ├── sessionManager.ts       # Session lifecycle
│   │   ├── session.ts              # Individual session (run/pause/resume)
│   │   ├── contextCoordinator.ts   # Cross-agent context sharing
│   │   ├── conflictResolver.ts     # Output conflict detection
│   │   ├── dependencyResolver.ts   # DAG scheduling
│   │   ├── retry.ts                # Backoff + error classification
│   │   ├── sessionViewAdapter.ts   # State → chat status mapping
│   │   ├── vscodeAdapters.ts       # VS Code API wrappers
│   │   └── types.ts
│   ├── execution/          # Agent execution
│   │   ├── agents/
│   │   │   ├── baseAgent.ts        # Abstract base with shared logic
│   │   │   ├── claudeAgent.ts      # Claude-specific prompting
│   │   │   ├── copilotAgent.ts     # Copilot-specific prompting
│   │   │   ├── codexAgent.ts       # Codex-specific prompting
│   │   │   ├── agentFactory.ts     # Factory for agent creation
│   │   │   └── types.ts
│   │   ├── toolApprover.ts         # Tool use approval logic
│   │   └── qualityGates.ts         # Output validation gates
│   ├── ui/                 # Webview providers
│   │   ├── dashboardProvider.ts    # Dashboard webview
│   │   ├── dashboardProtocol.ts    # Dashboard message types
│   │   ├── settingsProvider.ts     # Settings webview
│   │   └── settingsProtocol.ts     # Settings message types
│   ├── settings/           # Configuration management
│   │   ├── settingsService.ts      # Defaults, validation, resolution
│   │   ├── vscodeSettingsAdapter.ts # VS Code config bridge
│   │   └── types.ts
│   ├── utils/              # Error handling + telemetry
│   │   ├── errors.ts               # Typed error hierarchy
│   │   ├── errorRecovery.ts        # Fallback, rate limiting, state
│   │   └── telemetry.ts            # Local error frequency tracking
│   ├── test/
│   │   ├── mocks/vscode.ts         # VS Code API mock
│   │   ├── fixtures.ts             # Shared test factories
│   │   └── integration/            # Cross-module integration tests
│   └── extension.ts        # Entry point + chat participant
├── media/                   # Webview assets (CSS, JS)
├── docs/                    # Documentation
├── examples/                # Example project configurations
├── package.json             # Extension manifest
├── tsconfig.json            # TypeScript config
└── vitest.config.ts         # Test + coverage config

Testing

# Run all 741 tests
npm test

# Run with coverage report (requires >80%)
npm run test:coverage

# Run a specific test file
npx vitest run src/intelligence/intentAnalyzer.test.ts

# Watch mode
npx vitest --watch

Troubleshooting

"No language model available"

GitHub Copilot must be active and signed in. The extension uses the Copilot Language Model API to power all three agent types.

Agent selection seems wrong

Check your packai.agentPreferences.selectionStrategy setting. The default intelligent mode uses task signals; try preferClaude or preferCopilot to force a specific agent.

Dashboard not updating

Run "PackAI: Open Dashboard" from the Command Palette to focus the panel. The dashboard only receives events when it's visible.

Extension not activating

Ensure your VS Code version is 1.109+ and the extension is enabled. Check the "PackAI" output channel for logs.

Tests failing after changes

Run npx tsc --noEmit first to check for TypeScript errors, then npx vitest run to see which tests fail. Integration tests in src/test/integration/ test cross-module behavior.

Documentation

• Architecture Overview -- system design and module responsibilities
• User Guide -- detailed feature walkthrough
• Template Creation Guide -- creating custom workflow templates
• Contributing Guide -- development workflow and conventions
• API Reference -- public API documentation
• Changelog -- version history

License

MIT