Common use cases

Each task in this document includes clear instructions, example commands, and best practices to help you get the most from BLACKBOX CLI.

Create new projects from scratch

Build a complete web application

Suppose you want to create a full-featured web application with modern technologies.

1. Start BLACKBOX CLI session

   blackbox session
   
2. Request project creation

   > create a todo list web app using React, TypeScript, and Tailwind CSS
   
3. Add advanced features

   > add user authentication and data persistence to the todo app
   

   > implement drag-and-drop functionality for reordering tasks
   

   > add dark mode toggle and responsive design
   
4. Set up development environment

   > configure the development server and build scripts
   

Tips:

• Start with a clear description of what you want to build
• Ask for modern best practices and technologies
• Request proper project structure and organization

Generate API backends

Suppose you need to create a REST API for your application.

1. Specify API requirements

   > create a Node.js Express API for a blog application with user management
   
2. Add database integration

   > add PostgreSQL database integration with Prisma ORM
   
3. Implement authentication

   > add JWT authentication and authorization middleware
   
4. Add comprehensive endpoints

   > create CRUD endpoints for posts, comments, and user profiles
   

Tips:

• Specify the database and ORM you prefer
• Request proper error handling and validation
• Ask for API documentation generation

---

Debug and fix existing code

Suppose you’ve encountered errors in your application and need to identify and fix them quickly.

1. Describe the problem

   > my React app crashes when users try to submit the contact form
   
2. Let BLACKBOX CLI analyze the issue

   > analyze the contact form component and find the bug
   
3. Apply the recommended fix

   > fix the form validation error and add proper error handling
   
4. Test the solution

   > test the contact form to ensure it works correctly now
   

Tips:

• Provide specific error messages when available
• Mention the steps to reproduce the issue
• Ask for explanations of why the bug occurred

---

Improve and optimize existing code

Suppose you need to enhance the performance and maintainability of your codebase.

1. Identify optimization opportunities

   > analyze my React components for performance issues
   
2. Apply performance improvements

   > optimize the user dashboard component to reduce re-renders
   
3. Refactor for better maintainability

   > refactor the authentication logic into reusable hooks
   
4. Add modern patterns

   > update the state management to use React Query for server state
   

Tips:

• Ask for specific performance metrics and improvements
• Request explanations of optimization techniques used
• Focus on one area at a time for manageable changes

---

Add new features to existing projects

Suppose you want to extend your application with additional functionality.

1. Analyze current architecture

   > review my e-commerce app structure and suggest where to add a wishlist feature
   
2. Implement the new feature

   > add a wishlist feature with add/remove functionality and persistence
   
3. Integrate with existing components

   > update the product cards to include wishlist buttons
   
4. Add supporting features

   > create a wishlist page where users can view and manage saved items
   

Tips:

• Consider how new features integrate with existing code
• Ask for consistent styling and user experience
• Request proper testing for new functionality

---

Set up development environments

Suppose you need to configure a complete development environment for your project.

1. Configure build tools

   > set up Webpack configuration for my React TypeScript project
   
2. Add development server

   > configure hot reloading and development server with proxy settings
   
3. Set up testing environment

   > configure Jest and React Testing Library for unit testing
   
4. Add code quality tools

   > set up ESLint, Prettier, and Husky for code formatting and pre-commit hooks
   

Tips:

• Ask for modern development best practices
• Request configuration for your specific tech stack
• Include deployment preparation in your setup

---

Generate comprehensive tests

Suppose you need to add thorough testing coverage to your application.

1. Analyze testing needs

   > identify which components and functions need test coverage
   
2. Generate unit tests

   > create comprehensive unit tests for the user authentication service
   
3. Add integration tests

   > write integration tests for the shopping cart functionality
   
4. Create end-to-end tests

   > set up Cypress tests for the complete user registration flow
   

Tips:

• Ask for tests that cover edge cases and error conditions
• Request both positive and negative test scenarios
• Include tests for user interactions and API calls

---

Deploy applications

Suppose you need to deploy your application to production.

1. Prepare for deployment

   > optimize my React app for production deployment
   
2. Configure deployment platform

   > set up deployment to Vercel with environment variables
   
3. Set up CI/CD pipeline

   > create GitHub Actions workflow for automated testing and deployment
   
4. Configure monitoring

   > add error tracking and performance monitoring to the deployed app
   

Tips:

• Specify your preferred deployment platform
• Ask for environment-specific configurations
• Include monitoring and error handling setup

---

Work with databases

Suppose you need to design and implement database functionality.

1. Design database schema

   > design a PostgreSQL schema for a social media application
   
2. Set up database connection

   > configure Prisma ORM with PostgreSQL for my Node.js API
   
3. Create database operations

   > implement CRUD operations for users, posts, and comments
   
4. Add advanced queries

   > create queries for user feed with pagination and filtering
   

Tips:

• Specify your database technology and ORM preferences
• Ask for proper indexing and performance considerations
• Request data validation and security measures

---

Convert between technologies

Suppose you need to migrate or convert your project to different technologies.

1. Analyze current implementation

   > review my jQuery application and plan migration to React
   
2. Convert components gradually

   > convert the user dashboard from jQuery to React component
   
3. Update styling approach

   > migrate CSS styles to Tailwind CSS classes
   
4. Modernize JavaScript

   > convert JavaScript functions to TypeScript with proper types
   

Tips:

• Plan migrations in small, manageable steps
• Ask for compatibility considerations during transition
• Request testing strategies for converted code

---

Learn and understand code

Suppose you need to understand an existing codebase or learn new concepts.

1. Get project overview

   > explain the architecture and main components of this React application
   
2. Understand specific patterns

   > explain how the state management works in this Redux setup
   
3. Learn implementation details

   > walk me through how user authentication is implemented here
   
4. Get improvement suggestions

   > suggest modern alternatives to the patterns used in this codebase
   

Tips:

• Ask for explanations in terms you understand
• Request examples and comparisons to familiar concepts
• Focus on one area at a time for better comprehension

---

Manage concurrent development workflows with Git worktrees

Imagine you need to tackle multiple coding tasks at the same time while keeping each Blackbox CLI instance completely separate for better context of changes and isolation of work.

1. What is Git worktrees

   Git worktrees let you check out different branches from the same repository into separate folders. Each folder gets its own working directory with independent files, but they all share the same Git history. Check out the official Git worktree guide for more details.

2. Set up a new worktree

   # Set up a new worktree with a fresh branch
   git worktree add ../my-new-feature -b enhancement-ui
   
   # Or set up a worktree for an existing branch
   git worktree add ../my-app-fix fix-login-issue
   

   This creates a separate folder with an independent copy of your repository.

3. Launch Blackbox CLI in each worktree

   # Move to your worktree directory
   cd ../my-new-feature
   
   # Start Blackbox CLI in this isolated space
   blackbox
   
4. Launch Blackbox CLI in another worktree

   cd ../my-app-fix
   blackbox
   
5. Oversee your worktrees

   # View all active worktrees
   git worktree list
   
   # Clean up a worktree when finished
   git worktree remove ../my-new-feature
   

Tips:

• Each worktree maintains its own file state, ideal for simultaneous Blackbox CLI sessions
• Modifications in one worktree don’t impact others, ensuring Blackbox instances operate independently
• All worktrees access the same Git history and remote repositories
• For extended tasks, let Blackbox work in one worktree while you code in another
• Choose clear folder names to quickly identify each worktree’s purpose
• Set up your development environment in each new worktree based on your project’s needs, which may involve:
  • JavaScript projects: Installing dependencies (npm install, yarn install)
  • Python projects: Creating virtual environments or using package managers
  • Other languages: Following your project’s standard initialization steps

---

Ask Blackbox CLI about its own capabilities through direct queries

Want to learn more about Blackbox and its capabilities? Why not ask the agent itself for detailed insights and guidance. BlackBox CLI has access to its own documentation and can answer questions about its features and limitations.

Example queries to explore BLACKBOX AI

Start a session with blackbox and try these example prompts:

> what are the main features of Blackbox CLI and how do they help developers?

> Can BlackBox CLI create a pull request for me?

> What commands does BlackBox CLI support?

> what are some advanced tips for getting the most out of BLACKBOX AI sessions?

> how can I integrate Blackbox CLI with my existing development workflow?

BlackBox CLI provides documentation-based answers to these questions. For executable examples and hands-on demonstrations, refer to the specific use-case sections above.

Tips:

• Phrase your questions clearly to get precise, helpful responses
• Follow up on answers with more detailed queries for deeper understanding
• Use the agent’s knowledge to discover lesser-known features or optimizations
• Compare Blackbox capabilities with other tools by asking for side-by-side explanations

---

Compare multiple AI implementations with multi-agent execution

Suppose you want to see different approaches to solving the same problem and choose the best implementation. The /multi-agent command runs multiple AI agents in parallel, each working on a separate Git branch.

1. Ensure you're in a Git repository

   # Initialize Git if needed
   git init
   
   # Or navigate to an existing Git repository
   cd your-project
   
2. Use the /multi-agent command

   > /multi-agent create a REST API with user authentication, JWT tokens, and CRUD operations for a blog
   

   BLACKBOX CLI will automatically:

   • Create separate branches for each agent (Claude, Blackbox, and Codex if OpenAI key is configured)
   • Run all agents in parallel
   • Each agent implements the task independently on its own branch
3. Review the implementations

   # List all branches created
   git branch
   
   # Check out each branch to review
   git checkout multi-agent-claude-<timestamp>
   git checkout multi-agent-blackbox-<timestamp>
   git checkout multi-agent-codex-<timestamp>
   
4. Compare and select the best implementation

   Review each implementation for:

   • Code quality and structure
   • Error handling
   • Security practices
   • Performance considerations
   • Documentation and comments
5. Merge your preferred implementation

   # Switch to your main branch
   git checkout main
   
   # Merge the best implementation
   git merge multi-agent-claude-<timestamp>
   
   # Clean up unused branches
   git branch -D multi-agent-blackbox-<timestamp>
   git branch -D multi-agent-codex-<timestamp>
   git branch -D multi-agent-gemini-<timestamp>
   

Tips:

• Enable Codex: Configure your OpenAI API key with blackbox configure to get a third implementation from GPT-5.2 Codex
• Enable Gemini: Configure your GEMINI API key with blackbox configure to get a fourth implementation
• Complex Tasks: Use /multi-agent for complex features where multiple approaches provide valuable insights
• Security-Critical Code: Ideal for authentication, payment processing, or data handling implementations
• Learning: Great way to see different AI coding styles and best practices
• Branch Naming: Branches are automatically named with timestamps for easy identification
• Git Required: This feature only works in Git-initialized directories

Example scenarios for multi-agent execution

Building a payment integration:

> /multi-agent implement Stripe payment processing with webhook handling and error recovery

Creating authentication systems:

> /multi-agent build OAuth2 authentication with Google and GitHub providers

Developing complex algorithms:

> /multi-agent create a recommendation engine using collaborative filtering

Implementing data processing:

> /multi-agent build a data pipeline with ETL operations and error handling

What agents are included?

Default (with BLACKBOX API key):

• Claude: Anthropic’s Claude models - excellent for complex reasoning and detailed implementations
• Blackbox: BLACKBOX AI models - optimized for fast, efficient code generation

Additional (with OpenAI API & GEMINI API key key):

• Codex: OpenAI’s GPT-5.2 Codex - advanced code generation with broad language support
• Gemini: Gemini’s implementation for the multi agent.

Each agent works independently on its own branch, allowing you to compare different architectural decisions, coding patterns, and implementation strategies. This is particularly valuable for learning and ensuring code quality.

---