blackbox-vscode

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