Blackbox Code

Blackbox Code is a powerful command-line AI workflow tool adapted from Gemini CLI (details), specifically optimized for Blackbox3-Coder models. It enhances your development workflow with advanced code understanding, automated tasks, and intelligent assistance.

💡 Free Options Available

Get started with Blackbox Code at no cost using any of these free options:

$3

- 2,000 requests per day with no token limits
- 60 requests per minute rate limit
- Simply run blackbox and authenticate with your blackbox.ai account
- Automatic credential management and refresh
- Use /auth command to switch to Blackbox OAuth if you have initialized with OpenAI compatible mode

$3

- Mainland China: ModelScope offers 2,000 free API calls per day
- International: OpenRouter provides up to 1,000 free API calls per day worldwide

For detailed setup instructions, see Authorization.

> [!WARNING]
> Token Usage Notice: Blackbox Code may issue multiple API calls per cycle, resulting in higher token usage (similar to Claude Code). We're actively optimizing API efficiency.

Key Features

- Code Understanding & Editing - Query and edit large codebases beyond traditional context window limits
- Workflow Automation - Automate operational tasks like handling pull requests and complex rebases
- Enhanced Parser - Adapted parser specifically optimized for BlackboxAI models
- Vision Model Support - Automatically detect images in your input and seamlessly switch to vision-capable models for multimodal analysis

Installation

$3

Ensure you have Node.js version 20 or higher installed.

``bash
curl -qL https://www.npmjs.com/install.sh | sh
`

$3

`bash
npm install -g @lk_blackboxai/blackbox-cli@latest
blackbox --version
`

$3

`bash
git clone https://github.com/llmcod/blackbox_cli.git
cd blackbox-cli
npm install
npm install -g .
`

$3

`bash
brew install blackbox-cli
`

Quick Start

`bash


Start Blackbox Code

Create or edit .blackboxcli/settings.json in your home directory:

`json
{
"sessionTokenLimit": 32000
}
`

#### Session Commands

- /compress - Compress conversation history to continue within token limits
- /clear - Clear all conversation history and start fresh
- /stats - Check current token usage and limits

> 📝 Note: Session token limit applies to a single conversation, not cumulative API calls.

$3

Blackbox Code includes intelligent vision model auto-switching that detects images in your input and can automatically switch to vision-capable models for multimodal analysis. This feature is enabled by default - when you include images in your queries, you'll see a dialog asking how you'd like to handle the vision model switch.

#### Skip the Switch Dialog (Optional)

If you don't want to see the interactive dialog each time, configure the default behavior in your .blackboxcli/settings.json:

`json
{
"experimental": {
"vlmSwitchMode": "once"
}
}
`

Available modes:

- "once" - Switch to vision model for this query only, then revert
- "session" - Switch to vision model for the entire session
- "persist" - Continue with current model (no switching)
- Not set - Show interactive dialog each time (default)

#### Command Line Override

You can also set the behavior via command line:

`bash


Switch once per query

To completely disable vision model support, add to your .blackboxcli/settings.json:

`json
{
"experimental": {
"visionModelPreview": false
}
}
`

> 💡 Tip: In YOLO mode (--yolo), vision switching happens automatically without prompts when images are detected.

$3

Choose your preferred authentication method based on your needs:

#### 1. Blackbox OAuth (🚀 Recommended - Start in 30 seconds)

The easiest way to get started - completely free with generous quotas:

`bash


Just run this command and follow the browser authentication

`bash
export OPENAI_API_KEY="your_api_key_here"
export OPENAI_BASE_URL="your_api_endpoint"
export OPENAI_MODEL="your_model_choice"
`

2. Project .env File
Create a .env file in your project root:
`env
OPENAI_API_KEY=your_api_key_here
OPENAI_BASE_URL=your_api_endpoint
OPENAI_MODEL=your_model_choice
`

API Provider Options

> ⚠️ Regional Notice:
>
> - Mainland China: Use Alibaba Cloud Bailian or ModelScope
> - International: Use Alibaba Cloud ModelStudio or OpenRouter

Usage Examples

$3

`bash
cd your-project/
blackbox

Architecture analysis

`bash


Refactoring

`bash


Git automation

`bash


Performance analysis

`text
> What are the core business logic components?
> What security mechanisms are in place?
> How does the data flow through the system?
> What are the main design patterns used?
> Generate a dependency graph for this module
`

$3

`text
> What parts of this module can be optimized?
> Help me refactor this class to follow SOLID principles
> Add proper error handling and logging
> Convert callbacks to async/await pattern
> Implement caching for expensive operations
`

$3

`text
> Generate comprehensive JSDoc comments for all public APIs
> Write unit tests with edge cases for this component
> Create API documentation in OpenAPI format
> Add inline comments explaining complex algorithms
> Generate a README for this module
`

$3

`text
> Set up a new Express server with authentication
> Create a React component with TypeScript and tests
> Implement a rate limiter middleware
> Add database migrations for new schema
> Configure CI/CD pipeline for this project
`

Commands & Shortcuts

$3

- /help - Display available commands
- /clear - Clear conversation history
- /compress - Compress history to save tokens
- /stats - Show current session information
- /exit or /quit - Exit Blackbox Code

$3

- Ctrl+C - Cancel current operation
- Ctrl+D - Exit (on empty line)
- Up/Down` - Navigate command history

Benchmark Results

$3

| Agent | Model | Accuracy |
| --------- | ------------------ | -------- |
| Blackbox Code | Blackbox3-Coder-480A35 | 37.5% |
| Blackbox Code | Blackbox3-Coder-30BA3B | 31.3% |

Development & Contributing

See CONTRIBUTING.md to learn how to contribute to the project.

For detailed authentication setup, see the authentication guide.

Troubleshooting

If you encounter issues, check the troubleshooting guide.

Acknowledgments

This project is based on Google Gemini CLI. We acknowledge and appreciate the excellent work of the Gemini CLI team. Our main contribution focuses on parser-level adaptations to better support BlackboxAI models.

License

LICENSE

Star History