blackbox-desktop

name: blackbox-desktop description: > Guides usage of the Blackbox AI Desktop Agent, including desktop automation, MCP client connections, control modes (Full Autonomy, Approval Required, Chat Only), and .blackboxignore file exclusion. Activates when configuring or troubleshooting the Desktop Agent. compatibility: > Requires Blackbox Desktop Agent installed. Available for macOS, Windows, and Linux. metadata: author: tradecraft version: "1.0.0"

Blackbox AI Desktop Agent

The Blackbox AI Desktop Agent is a standalone application for Windows, macOS, and Linux that provides AI-powered coding assistance with full autonomy controls, MCP client integration, and cross-application automation.

When to Use This Skill

• Installing the Blackbox Desktop Agent on any OS
• Configuring control modes (Full Autonomy, Approval Required, Chat Only)
• Setting up MCP (Model Context Protocol) client connections
• Creating .blackboxignore files for file exclusion
• Managing token usage and session settings
• Understanding security and encryption features
• Running cross-application automation workflows

Quick Start

Install

Download from app.blackbox.ai:

Setup

1. Install and launch the application
2. Sign in with your Blackbox AI account
3. Choose your control mode
4. Start coding with AI assistance

Core Concepts

Control Modes

Switch modes from the agent settings panel.

MCP Client Setup

The Desktop Agent acts as an MCP (Model Context Protocol) client, connecting to external tools and services.

Generate MCP Token:

1. Go to cloud.blackbox.ai
2. Open profile settings
3. Find "MCP Token" section
4. Click generate

Connect MCP Server:

blackbox mcp add remote-code https://cloud.blackbox.ai/api/mcp \
  -t http \
  -H "Authorization: Bearer <your-mcp-token>"

Verify: Look for "using 1:MCP server" in terminal output.

Discover tools: Press Ctrl+t or ask "print all the remote-code tools"

See references/mcp-setup.md for detailed MCP configuration.

File Exclusion

Create a .blackboxignore file in your project root:

# .blackboxignore
node_modules/
dist/
build/
.env
.env.local
*.log
*.lock
coverage/
.next/
__pycache__/

Same syntax as .gitignore. Excludes files from:

• Context indexing
• Token consumption
• AI analysis

Security Features

Common Patterns

Full Autonomy Workflow

1. Set mode to "Full Autonomy"
2. Describe the task: "Refactor all API routes to use Zod validation"
3. Agent works through all files autonomously
4. Review changes in git diff when complete

Approval-Based Development

1. Set mode to "Approval Required"
2. Ask: "Add error handling to the payment processing module"
3. Review each proposed change
4. Approve or reject individually

MCP-Enhanced Workflow

1. Connect MCP servers for external tools
2. Agent can now access remote resources
3. "Use the database MCP to check the current schema, then add a migration"

Troubleshooting

References

• See references/capabilities.md for full capability list
• See references/mcp-setup.md for MCP server configuration