---
name: blackbox-vscode
description: >
  Guides usage of the Blackbox AI VS Code extension, including IDE agent modes,
  sub-agent orchestration, voice mode, browser automation, auto-approval settings,
  model selection, and context integration with files, URLs, and git. Activates when
  configuring or using the Blackbox VS Code extension.
compatibility: >
  Requires VS Code with Blackbox AI extension installed (marketplace ID: Blackbox.blackbox).
metadata:
  author: tradecraft
  version: "1.0.0"
---

# Blackbox AI VS Code Extension

The Blackbox AI VS Code extension (4.7M+ installs) provides an AI coding agent directly in your IDE with auto/manual/voice modes, sub-agent orchestration, browser automation, and access to 300+ models.

## When to Use This Skill

- Installing or configuring the Blackbox AI VS Code extension
- Switching between Auto, Manual, and Voice modes
- Setting up sub-agent orchestration for parallel task execution
- Using browser automation tools in VS Code
- Configuring auto-approval settings for file edits and commands
- Adding context via URLs, git commits, files, or folders
- Selecting models or configuring the chairman LLM
- Using `/cli` background tasks with worktree isolation

## Quick Start

### Install

1. Open VS Code Extensions (`Ctrl+Shift+X` / `Cmd+Shift+X`)
2. Search for **"BLACKBOX AI"**
3. Click **Install**
4. Click the AI Agent icon on the right sidebar
5. Authenticate with your Blackbox AI account

### Start Using

Open the AI chat panel and type your request:

```
> Create a React component for a user profile card with avatar, name, and bio
```

## Core Concepts

### Agent Modes

| Mode | Description | Best For |
|------|-------------|----------|
| **Manual** | Approve each action before execution | Sensitive codebases, learning |
| **Auto** | Automatically executes approved actions | Fast iteration, trusted tasks |
| **Voice** | Hands-free via speech-to-text/text-to-speech | Brainstorming, accessibility |

Switch modes from the chat interface controls.

### Auto-Approval Settings

When Auto mode is enabled, independently toggle approval for:

| Action | Description |
|--------|-------------|
| Edit file | Modify existing files |
| Create file | Create new files |
| Command execution | Run terminal commands |
| Read file | Read file contents |

Access via: **Controls icon** (next to settings button) → **Tools configuration**

### Context Integration

Add context to your prompts using `@`:

| Context Type | How to Use |
|-------------|------------|
| **Files** | `@filename.ts` — reference specific files |
| **Folders** | `@src/components/` — reference directories |
| **URLs** | Paste web URLs for documentation context |
| **Git Commits** | Reference specific commits for history |
| **Conversation** | Previous chat messages provide continuity |

### Sub-Agent Orchestration

Blackbox breaks complex tasks into sub-tasks and runs them in parallel:

1. Main agent analyzes and decomposes the task
2. Sub-agents spawn in dedicated terminal instances (via Blackbox CLI)
3. Each sub-agent handles a specific sub-task concurrently
4. Main agent coordinates and consolidates results

**Requirements:** Blackbox CLI must be installed and configured.

**Best for:**
- Large feature implementations
- Complex bug fixes requiring multiple approaches
- Refactoring across many files

See `references/orchestration.md` for details.

### Voice Mode

Powered by **ElevenLabs** speech-to-text and text-to-speech.

**Enable:** Click the voice mode button (between add context and camera buttons).

**Capabilities:**
- Code analysis and structure inquiries
- Code editing and refactoring requests
- Debugging assistance
- Feature development guidance
- Repository insights

**Controls:**
- **Mute** — pause voice input
- **Hang-up** — disable voice mode

### Browser Automation

The browser tool allows the agent to:

- Launch and control a browser
- Navigate websites and interact with elements
- Capture screenshots
- Test web applications in real-time

**Setup:** Enable Playwright via the Extensions page.

### Background CLI Tasks (`/cli`)

Run tasks in the background without blocking your main workflow:

```
/cli
```

**Modes:**
| Mode | Description |
|------|-------------|
| **Workspace** | Runs in current workspace |
| **Worktree** | Creates isolated `worktree-<timestamp>` branch |

Output streams live in the VS Code Terminal Editor tab. Multiple sessions can run in parallel. Worktree mode is recommended to avoid conflicts.

### Model Selection

Access 300+ models including:

- **OpenAI:** GPT-4o, GPT-5, GPT-5.2 Codex
- **Anthropic:** Claude Sonnet 4, Claude Opus 4.5
- **Google:** Gemini 2.5 Pro, Gemini 2.5 Flash
- **Meta:** Llama 3.1, Llama 4
- **DeepSeek:** V3 (free), R1 (free)
- **xAI:** Grok 3
- And many more

The **Chairman LLM** is an internal routing layer that compares outputs across models for complex tasks.

## Common Patterns

### Code Generation

```
> Create a REST API endpoint for /api/users with CRUD operations using Express and Zod validation
```

### Debugging

```
> @src/auth/login.ts This file throws a 401 error even with valid credentials. Debug the token validation logic.
```

### Code Review

```
> Review @src/components/Dashboard.tsx for performance issues, accessibility, and React best practices
```

### Project Generation

```
> Create a new Next.js 15 project with App Router, TypeScript, Tailwind, and Supabase auth
```

### Multi-File Refactor with Orchestration

```
> Refactor the authentication system to use the repository pattern. Update all services, controllers, and tests.
```

(Blackbox will use sub-agent orchestration to parallelize across files)

## Troubleshooting

| Issue | Fix |
|-------|-----|
| Extension not loading | Restart VS Code, check for updates |
| Authentication fails | Sign out and re-authenticate |
| Voice mode not working | Check microphone permissions |
| Sub-agents not spawning | Install and configure Blackbox CLI |
| Browser tool unavailable | Enable Playwright in Extensions |
| Auto mode too aggressive | Fine-tune auto-approval toggles |

## References

- See `references/configuration.md` for settings and auto-approval config
- See `references/orchestration.md` for sub-agent parallel execution
- See `references/context-integration.md` for context types and usage