> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blackbox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Steps>
  <Step title="Start BLACKBOX CLI session">
    ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    blackbox session
    ```
  </Step>

  <Step title="Request project creation">
    ```
    > create a todo list web app using React, TypeScript, and Tailwind CSS
    ```
  </Step>

  <Step title="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
    ```
  </Step>

  <Step title="Set up development environment">
    ```
    > configure the development server and build scripts
    ```
  </Step>
</Steps>

<Tip>
  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
</Tip>

##### Generate API backends

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

<Steps>
  <Step title="Specify API requirements">
    ```
    > create a Node.js Express API for a blog application with user management
    ```
  </Step>

  <Step title="Add database integration">
    ```
    > add PostgreSQL database integration with Prisma ORM
    ```
  </Step>

  <Step title="Implement authentication">
    ```
    > add JWT authentication and authorization middleware
    ```
  </Step>

  <Step title="Add comprehensive endpoints">
    ```
    > create CRUD endpoints for posts, comments, and user profiles
    ```
  </Step>
</Steps>

<Tip>
  Tips:

  * Specify the database and ORM you prefer
  * Request proper error handling and validation
  * Ask for API documentation generation
</Tip>

***

## Debug and fix existing code

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

<Steps>
  <Step title="Describe the problem">
    ```
    > my React app crashes when users try to submit the contact form
    ```
  </Step>

  <Step title="Let BLACKBOX CLI analyze the issue">
    ```
    > analyze the contact form component and find the bug
    ```
  </Step>

  <Step title="Apply the recommended fix">
    ```
    > fix the form validation error and add proper error handling
    ```
  </Step>

  <Step title="Test the solution">
    ```
    > test the contact form to ensure it works correctly now
    ```
  </Step>
</Steps>

<Tip>
  Tips:

  * Provide specific error messages when available
  * Mention the steps to reproduce the issue
  * Ask for explanations of why the bug occurred
</Tip>

***

## Improve and optimize existing code

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

<Steps>
  <Step title="Identify optimization opportunities">
    ```
    > analyze my React components for performance issues
    ```
  </Step>

  <Step title="Apply performance improvements">
    ```
    > optimize the user dashboard component to reduce re-renders
    ```
  </Step>

  <Step title="Refactor for better maintainability">
    ```
    > refactor the authentication logic into reusable hooks
    ```
  </Step>

  <Step title="Add modern patterns">
    ```
    > update the state management to use React Query for server state
    ```
  </Step>
</Steps>

<Tip>
  Tips:

  * Ask for specific performance metrics and improvements
  * Request explanations of optimization techniques used
  * Focus on one area at a time for manageable changes
</Tip>

***

## Add new features to existing projects

Suppose you want to extend your application with additional functionality.

<Steps>
  <Step title="Analyze current architecture">
    ```
    > review my e-commerce app structure and suggest where to add a wishlist feature
    ```
  </Step>

  <Step title="Implement the new feature">
    ```
    > add a wishlist feature with add/remove functionality and persistence
    ```
  </Step>

  <Step title="Integrate with existing components">
    ```
    > update the product cards to include wishlist buttons
    ```
  </Step>

  <Step title="Add supporting features">
    ```
    > create a wishlist page where users can view and manage saved items
    ```
  </Step>
</Steps>

<Tip>
  Tips:

  * Consider how new features integrate with existing code
  * Ask for consistent styling and user experience
  * Request proper testing for new functionality
</Tip>

***

## Set up development environments

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

<Steps>
  <Step title="Configure build tools">
    ```
    > set up Webpack configuration for my React TypeScript project
    ```
  </Step>

  <Step title="Add development server">
    ```
    > configure hot reloading and development server with proxy settings
    ```
  </Step>

  <Step title="Set up testing environment">
    ```
    > configure Jest and React Testing Library for unit testing
    ```
  </Step>

  <Step title="Add code quality tools">
    ```
    > set up ESLint, Prettier, and Husky for code formatting and pre-commit hooks
    ```
  </Step>
</Steps>

<Tip>
  Tips:

  * Ask for modern development best practices
  * Request configuration for your specific tech stack
  * Include deployment preparation in your setup
</Tip>

***

## Generate comprehensive tests

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

<Steps>
  <Step title="Analyze testing needs">
    ```
    > identify which components and functions need test coverage
    ```
  </Step>

  <Step title="Generate unit tests">
    ```
    > create comprehensive unit tests for the user authentication service
    ```
  </Step>

  <Step title="Add integration tests">
    ```
    > write integration tests for the shopping cart functionality
    ```
  </Step>

  <Step title="Create end-to-end tests">
    ```
    > set up Cypress tests for the complete user registration flow
    ```
  </Step>
</Steps>

<Tip>
  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
</Tip>

***

## Deploy applications

Suppose you need to deploy your application to production.

<Steps>
  <Step title="Prepare for deployment">
    ```
    > optimize my React app for production deployment
    ```
  </Step>

  <Step title="Configure deployment platform">
    ```
    > set up deployment to Vercel with environment variables
    ```
  </Step>

  <Step title="Set up CI/CD pipeline">
    ```
    > create GitHub Actions workflow for automated testing and deployment
    ```
  </Step>

  <Step title="Configure monitoring">
    ```
    > add error tracking and performance monitoring to the deployed app
    ```
  </Step>
</Steps>

<Tip>
  Tips:

  * Specify your preferred deployment platform
  * Ask for environment-specific configurations
  * Include monitoring and error handling setup
</Tip>

***

## Work with databases

Suppose you need to design and implement database functionality.

<Steps>
  <Step title="Design database schema">
    ```
    > design a PostgreSQL schema for a social media application
    ```
  </Step>

  <Step title="Set up database connection">
    ```
    > configure Prisma ORM with PostgreSQL for my Node.js API
    ```
  </Step>

  <Step title="Create database operations">
    ```
    > implement CRUD operations for users, posts, and comments
    ```
  </Step>

  <Step title="Add advanced queries">
    ```
    > create queries for user feed with pagination and filtering
    ```
  </Step>
</Steps>

<Tip>
  Tips:

  * Specify your database technology and ORM preferences
  * Ask for proper indexing and performance considerations
  * Request data validation and security measures
</Tip>

***

## Convert between technologies

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

<Steps>
  <Step title="Analyze current implementation">
    ```
    > review my jQuery application and plan migration to React
    ```
  </Step>

  <Step title="Convert components gradually">
    ```
    > convert the user dashboard from jQuery to React component
    ```
  </Step>

  <Step title="Update styling approach">
    ```
    > migrate CSS styles to Tailwind CSS classes
    ```
  </Step>

  <Step title="Modernize JavaScript">
    ```
    > convert JavaScript functions to TypeScript with proper types
    ```
  </Step>
</Steps>

<Tip>
  Tips:

  * Plan migrations in small, manageable steps
  * Ask for compatibility considerations during transition
  * Request testing strategies for converted code
</Tip>

***

## Learn and understand code

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

<Steps>
  <Step title="Get project overview">
    ```
    > explain the architecture and main components of this React application
    ```
  </Step>

  <Step title="Understand specific patterns">
    ```
    > explain how the state management works in this Redux setup
    ```
  </Step>

  <Step title="Learn implementation details">
    ```
    > walk me through how user authentication is implemented here
    ```
  </Step>

  <Step title="Get improvement suggestions">
    ```
    > suggest modern alternatives to the patterns used in this codebase
    ```
  </Step>
</Steps>

<Tip>
  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
</Tip>

***

## 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.

<Steps>
  <Step title="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](https://git-scm.com/docs/git-worktree) for more details.
  </Step>

  <Step title="Set up a new worktree">
    ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    # 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.
  </Step>

  <Step title="Launch Blackbox CLI in each worktree">
    ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    # Move to your worktree directory
    cd ../my-new-feature

    # Start Blackbox CLI in this isolated space
    blackbox
    ```
  </Step>

  <Step title="Launch Blackbox CLI in another worktree">
    ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    cd ../my-app-fix
    blackbox
    ```
  </Step>

  <Step title="Oversee your worktrees">
    ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    # View all active worktrees
    git worktree list

    # Clean up a worktree when finished
    git worktree remove ../my-new-feature
    ```
  </Step>
</Steps>

<Tip>
  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
</Tip>

***

## 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?
```

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

<Tip>
  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
</Tip>

***

## 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.

<Steps>
  <Step title="Ensure you're in a Git repository">
    ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    # Initialize Git if needed
    git init

    # Or navigate to an existing Git repository
    cd your-project
    ```
  </Step>

  <Step title="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
  </Step>

  <Step title="Review the implementations">
    ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    # 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>
    ```
  </Step>

  <Step title="Compare and select the best implementation">
    Review each implementation for:

    * Code quality and structure
    * Error handling
    * Security practices
    * Performance considerations
    * Documentation and comments
  </Step>

  <Step title="Merge your preferred implementation">
    ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    # 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>
    ```
  </Step>
</Steps>

<Tip>
  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
</Tip>

##### 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.

<Note>
  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.
</Note>

***