### Get Profile Packages Example

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/profile-system.md

Example of how to get a space-separated list of apt packages for a given profile name using the `get_profile_packages` function.

```bash
get_profile_packages "c"
# Returns: "gdb valgrind clang ... libncurses5-dev"
```

--------------------------------

### Install Claudebox for Development

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/configuration.md

Set up Claudebox for development by cloning the repository, building the installer, and then running the installer. This is useful for contributing to the project.

```bash
git clone https://github.com/RchGrav/claudebox.git claudebox
cd claudebox
bash .builder/build.sh    # Builds self-extracting installer
./claudebox.run           # Installs
```

--------------------------------

### Claudebox Setup Commands

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/00-START-HERE.md

Commands to initialize Claudebox, add development profiles, and install packages.

```bash
claudebox create                    # Create first slot
```

```bash
claudebox add python               # Add development profile
```

```bash
claudebox install vim              # Install apt package
```

--------------------------------

### C/C++ Development Environment Setup

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/profile-system.md

Set up a C/C++ development environment with GCC/G++, Clang, Make, CMake, debuggers, and analyzers. Installs GDB TUI as an extra.

```bash
claudebox add c
claudebox install gdb-tui
```

--------------------------------

### Expand Profile Example

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/profile-system.md

Example of how to expand a profile name to include its dependencies, returning a space-separated list of all required profiles.

```bash
expand_profile "c"
# Returns: "core build-tools c"
```

--------------------------------

### Install Packages with Claudebox

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/profile-system.md

Installs specified packages. These packages are added to the `[packages]` section in `profiles.ini` and are installed on-the-fly in the next container start via `apt-get`. They persist across container restarts.

```bash
claudebox install htop vim tmux
```

--------------------------------

### Development Installation

Source: https://github.com/rchgrav/claudebox/blob/main/README.md

Clone the repository to develop or test the latest changes. This involves cloning, building the installer, and then running it.

```bash
# Clone the repository
git clone https://github.com/RchGrav/claudebox.git
cd claudebox

# Build the installer
bash .builder/build.sh

# Run the installer
./claudebox.run
```

--------------------------------

### Install Claudebox

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/README.md

Download the latest release, make it executable, and run the installer.

```bash
wget https://github.com/RchGrav/claudebox/releases/latest/download/claudebox.run
chmod +x claudebox.run
./claudebox.run
```

--------------------------------

### Install Docker Interactively

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/library-api.md

Initiates an interactive Docker installation process. It prompts for user confirmation, detects the operating system, and installs Docker for supported distributions. The function automatically calls `configure_docker_nonroot()` upon successful installation. Exits with an error if the OS is not supported.

```bash
install_docker
```

--------------------------------

### Full Stack Environment Setup

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/profile-system.md

Combine Python (ML), JavaScript, and DevOps profiles for a comprehensive full-stack development environment. Installs Jupyter as an extra.

```bash
claudebox add python ml
claudebox add javascript
claudebox add devops
claudebox install jupyter
```

--------------------------------

### install_docker()

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/library-api.md

Installs Docker on the system interactively. It detects the operating system and installs Docker for supported distributions, then configures it for non-root users.

```APIDOC
## install_docker()

### Description
Install Docker (interactive).

### Behavior
- Prompts user for confirmation
- Detects OS via `/etc/os-release`
- Installs Docker for Ubuntu, Debian, Fedora, CentOS, Arch
- Calls `configure_docker_nonroot()` after install
- Exits with error if OS unsupported

### Supported OS
Ubuntu, Debian, Fedora, RHEL, CentOS, Arch, Manjaro

### Example
```bash
install_docker
```
```

--------------------------------

### Quick Project Setup

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/quick-reference.md

A sequence of commands to quickly set up a new project with Python and Rust support and enter a shell.

```bash
claudebox create && claudebox add python rust && claudebox shell
```

--------------------------------

### Troubleshooting: Docker Installation Prompt

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/README.md

If Docker is not installed, running 'claudebox' will prompt for auto-installation.

```bash
claudebox
```

--------------------------------

### View Project Information

Source: https://github.com/rchgrav/claudebox/blob/main/README.md

Command to display comprehensive information about the current Claudebox setup, including project details, installation paths, saved flags, custom commands, installed profiles, Docker status, and a summary of all projects.

```bash
# Show detailed project and system information
claudebox info
```

--------------------------------

### Install Recommended Tmux Configuration

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/configuration.md

Installs the recommended tmux configuration to `~/.tmux.conf`. This enables features like Ctrl+Alt+arrow navigation and Ctrl+Alt+0 zoom.

```bash
claudebox tmux conf
# Installs to ~/.tmux.conf
# Provides Ctrl+Alt+arrow navigation, Ctrl+Alt+0 zoom
```

--------------------------------

### Example Docker Image Name

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/container-system.md

Provides a concrete example of a Docker image name generated for a specific project path, demonstrating the application of the naming convention.

```text
Example: Project /home/alice/projects/website → Image claudebox-projects_website_a1b2c3d4
```

--------------------------------

### Download and Extract Archive Installation

Source: https://github.com/rchgrav/claudebox/blob/main/README.md

This method is for manual installation or custom locations. It involves downloading the archive, extracting it, and running a script to create a symlink.

```bash
# Download the archive
wget https://github.com/RchGrav/claudebox/releases/latest/download/claudebox-2.0.0.tar.gz

# Extract to your preferred location
mkdir -p ~/my-tools/claudebox
tar -xzf claudebox-2.0.0.tar.gz -C ~/my-tools/claudebox

# Run main.sh to create symlink
cd ~/my-tools/claudebox
./main.sh

# Or create your own symlink
ln -s ~/my-tools/claudebox/main.sh ~/.local/bin/claudebox
```

--------------------------------

### Multi-Stage Dockerfile Example

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/docker-integration.md

A Dockerfile demonstrating multi-stage builds to reduce the final image size by excluding build-time dependencies.

```dockerfile
FROM debian:bookworm AS builder
RUN apt-get install -y build-tools

FROM debian:bookworm AS runtime
COPY --from=builder /usr/lib /usr/lib
```

--------------------------------

### Build Flags Example

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/container-system.md

Demonstrates how to set environment variables to control the build process, such as forcing a rebuild or enabling verbose output.

```bash
REBUILD=true claudebox shell  # Force rebuild
--verbose claudebox shell      # Show build logs
```

--------------------------------

### BuildKit Secrets Mounting Example

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/docker-integration.md

Example of using BuildKit to securely mount secrets during a Docker build without baking them into the image.

```bash
docker build --secret github_token=<token> ...
RUN --mount=type=secret,id=github_token \
    export GITHUB_TOKEN=$(cat /run/secrets/github_token) && ...
```

--------------------------------

### Install Claudebox using Self-Extracting Installer

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/configuration.md

Execute the self-extracting installer to set up Claudebox. This method extracts the necessary files and creates a symlink for the command-line executable.

```bash
./claudebox.run
# Extracts to:
# ~/.claudebox/source/
# Creates symlink at:
# ~/.local/bin/claudebox
```

--------------------------------

### Data Science Environment Setup

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/profile-system.md

Configure a Data Science environment with R and Python, including common libraries like Jupyter, matplotlib, and pandas. Installs specified Python packages.

```bash
claudebox add datascience
claudebox add python
claudebox install jupyter matplotlib pandas
```

--------------------------------

### Single Development Workflow with Claudebox

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/README.md

Use this for a single developer's setup. 'claudebox create' is for one-time setup, and 'claudebox shell' is for daily use.

```bash
claudebox create              # One-time setup
claudebox shell               # Daily use
```

--------------------------------

### Manage Development Environment Profiles

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/quick-reference.md

Commands for viewing, adding, and installing development profiles and packages. Supports adding multiple profiles at once and installing extra system packages.

```bash
claudebox profiles     # See all 20+ profiles
claudebox add python   # Add Python profile
claudebox add c rust   # Add multiple profiles
claudebox install vim  # Install extra apt packages
```

--------------------------------

### ClaudeBox Profile Configuration Example

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/profile-system.md

Example of the INI file format used for ClaudeBox profile configuration. This file should not be edited manually.

```ini
# ClaudeBox Profile Configuration
# Do not edit manually - use: claudebox add/remove

[profiles]
core
python
rust

[packages]
htop
vim	mux
```

--------------------------------

### Verify Claudebox Installation

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/configuration.md

Run this command to display all configuration details, paths, and the current status of your Claudebox installation.

```bash
claudebox info
# Shows all configuration, paths, and status
```

--------------------------------

### Example Task Roadmap File Structure

Source: https://github.com/rchgrav/claudebox/blob/main/claude/CLAUDE.md

This is an example of a task roadmap file structure used for multi-PR task management. It includes sections for progress, key decisions, and next steps.

```markdown
# 2025-07-06-feature-improvements.md

## Progress
- ✅ PR 1: Testing Foundation
- ✅ PR 2: Service Authentication  
- 🔄 PR 3: Error Handling (in review)

## Key Decisions
- Using behavioral tests instead of implementation tests
- Async approach for better performance

## Next Steps
- PR 4: Individual Service Testing
- Need to integrate retry mechanism into API client

```

--------------------------------

### Dockerfile Base Image and Package Installation

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/docker-integration.md

Defines the base operating system and installs specified APT packages within the Dockerfile. The PACKAGES variable is substituted at build time.

```dockerfile
ARG PACKAGES="<space-separated-packages>"
RUN apt-get update && apt-get install -y ${PACKAGES}
```

--------------------------------

### Example Container Name

Source: https://github.com/rchgrav/claudebox/blob/main/docs/slot-management-system.md

An example of a fully formed container name following the defined convention.

```string
claudebox-home_rich_myproject_cc618e36-524b9a6e
```

--------------------------------

### ClaudeBox Network Allowlist Example

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/container-system.md

An example of a network allowlist file used to configure firewall rules for containers. Only specified domains can be accessed outbound.

```text
# ClaudeBox Network Allowlist
api.anthropic.com
github.com
*.githubusercontent.com
registry.npmjs.org
```

--------------------------------

### Claudebox Control Flags Example

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/cli-commands.md

Shows how to use control flags that are passed to the container to modify security and behavior. Examples include enabling sudo without a password and disabling firewall restrictions.

```bash
claudebox --enable-sudo shell
claudebox --disable-firewall shell
claudebox --enable-sudo --disable-firewall shell
```

--------------------------------

### Initialize and Configure Project

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/README.md

Create an authenticated slot, add development profiles, and launch the Claude shell for a new project.

```bash
cd ~/projects/myapp
claudebox create              # Create authenticated slot
claudebox add python rust     # Add development profiles
claudebox shell               # Launch Claude
```

--------------------------------

### Install Additional Apt Packages

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/cli-commands.md

Installs additional apt packages within the ClaudeBox container. These packages are added to the project's configuration and installed on-the-fly during the next container start.

```bash
claudebox install htop vim tmux
```

```bash
claudebox install pkg1 pkg2 pkg3
```

--------------------------------

### Slot Identity CRC32 Chain Example

Source: https://github.com/rchgrav/claudebox/blob/main/docs/slot-management-system.md

Illustrates the iterative CRC32 checksum generation for slot identification, starting from a base project path.

```text
Project path: /home/rich/myproject
Slot 0: cc618e36 (base CRC32)
Slot 1: 524b9a6e (CRC32 of "cc618e36")
Slot 2: ab89def0 (CRC32 of "524b9a6e")
```

--------------------------------

### Initialize Project Directory

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/library-api.md

Sets up the necessary directory structure and initial files for a new project. This function is idempotent and safe to call multiple times.

```bash
init_project_dir "$PROJECT_DIR"
```

--------------------------------

### Claudebox Container Runtime Initialization

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/README.md

Details the initialization process within a Claudebox container, including network firewall setup, package installation, Python virtual environment activation, and signal handling before launching the Claude Code CLI.

```bash
Container Runtime:
    ├── Entrypoint script initializes:
    │   ├── Network firewall (iptables + allowlist)
    │   ├── Extra packages (from profiles.ini)
    │   ├── Python venv (if Python profile)
    │   └── Signal handling
    ├── Claude Code CLI launched with auth from slot directory
    ├── Project code mounted at /workspace
    ├── Container auto-deletes on exit (--rm flag)
    └── Slot data persists in ~/.claudebox/projects/...
```

--------------------------------

### Dockerfile Layer Caching Strategy

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/docker-integration.md

Structure your Dockerfile with less frequently changing layers first to maximize cache utilization. This example separates base system, build tools, language packages, user setup, and scripts into distinct layers.

```dockerfile
# Layer 1: Base system (rarely changes)
FROM debian:bookworm
RUN apt-get update && apt-get install -y base-tools

# Layer 2: Build tools (occasionally changes)
RUN apt-get install -y cmake ninja

# Layer 3: Language-specific (frequently changes)
ARG PACKAGES=""
RUN apt-get install -y ${PACKAGES}

# Layer 4: User setup (rarely changes)
RUN useradd -u $UID -g $GID claude

# Layer 5: Scripts (rarely changes)
COPY docker-entrypoint /

```

--------------------------------

### Install Claudebox Manually

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/configuration.md

Manually install Claudebox by extracting the archive and creating a symbolic link to the main script. This provides more control over the installation location.

```bash
tar -xzf claudebox-2.0.0.tar.gz -C ~/my-claudebox/
ln -s ~/my-claudebox/main.sh ~/.local/bin/claudebox
```

--------------------------------

### Claudebox Help Commands

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/cli-commands.md

Provides examples of how to access help information for Claudebox and its subcommands. This includes general help, help for specific commands like 'claude', and help for 'profiles'.

```bash
claudebox help
claudebox help claude      # Show Claude CLI help
claudebox help profiles    # Show profiles command help
```

--------------------------------

### Install Additional Packages

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/quick-reference.md

Installs extra packages or tools into the ClaudeBox environment, such as vim or tmux.

```bash
claudebox install vim tmux
```

--------------------------------

### Create and promote a draft flow

Source: https://github.com/rchgrav/claudebox/blob/main/CLAUDE.md

First, create a draft with a name. Then, promote the draft to a specific version using its ID.

```bash
backlog draft create "Spike GraphQL" → backlog draft promote 3.1
```

--------------------------------

### Example Output Directory Structure

Source: https://github.com/rchgrav/claudebox/blob/main/commands/agentflow.md

This tree structure illustrates the expected organization of output files generated by the agent workflow. It helps in understanding where different phases and agent outputs will be stored.

```bash
./outputs/{task_name}_{timestamp}/
├── phase1/
│   ├── agentA_output.md
│   └── agentB_output.md
├── phase2/
│   ├── agentC_code.py
│   └── agentD_report.md
├── evaluations/
│   ├── phase1_evaluation.md
│   └── phase2_evaluation.md
└── final/
└── final_deliverable.pdf

```

--------------------------------

### Install markdown-tree-parser Globally

Source: https://github.com/rchgrav/claudebox/blob/main/commands/BMad/tasks/shard-doc.md

Install the markdown-tree-parser package globally using npm. This is required for automatic document sharding.

```bash
npm install -g @kayvan/markdown-tree-parser
```

--------------------------------

### init_project_dir(path)

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/library-api.md

Initializes the necessary directory structure and configuration files for a new project within the specified path. This operation is idempotent and safe to call multiple times.

```APIDOC
## init_project_dir(path)

### Description
Initialize project directory structure.

### Behavior
- Creates parent directory
- Creates `.project_path` file
- Creates `.project_container_counter` file (initialized to 1)
- Creates `profiles.ini`
- Creates `firewall/` directory
- Copies bundled commands
- Copies `common.sh` helper

### Idempotent
Safe to call multiple times

### Parameters
- **path** (string) - Project directory

### Returns
- Nothing

### Example
```bash
init_project_dir "$PROJECT_DIR"
```
```

--------------------------------

### Workflow Creation Summary Output

Source: https://github.com/rchgrav/claudebox/blob/main/commands/controlflow.md

Displays a summary of the created workflow, including key paths and the command to launch it.

```shell
✅ Created workflow: {workflow_name}
- Orchestrator: ~/.claude/commands/{workflow_name}.md
- Config: ~/.claudebox/meta/workflows/{workflow_name}/config.md
- Roles: ~/.claudebox/meta/workflows/{workflow_name}/roles/
- Outputs: ~/.claudebox/outputs/{workflow_name}_{timestamp}/

To launch: /project:{workflow_name}
```

--------------------------------

### Claudebox Project Creation Lifecycle

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/container-system.md

Illustrates the sequence of operations when a user creates a new project using the 'claudebox create' command, including directory initialization, container setup, and Docker execution.

```text
User runs: claudebox create
    ↓
init_project_dir(path)          # Create ~/.claudebox/projects/<parent>/
    ↓
read_counter() → max = 1
    ↓
Loop slots 1..1: Find dead slots? None found
    ↓
create_container(): idx = 2, name = crc32_word(crc32(path))
    ↓
init_slot_dir()                 # Create slot directories
    ↓
write_counter(parent, 2)        # Update for next time
    ↓
docker build (if needed)        # Build image from Dockerfile + profiles
    ↓
docker run [container] --rm -it # Launch interactive container
    ↓
[User authenticates with Anthropic API]
    ↓
[User exits container]
    ↓
Container auto-deletes (--rm flag)
Slot data persists in ~/.claudebox/projects/<parent>/<slot-name>/
    ↓
User later: claudebox shell
    ↓
find_ready_slot()               # Find slot 2 (authenticated + inactive)
    ↓
docker run [container] --rm -it # Launch same slot again
    ↓
[Credentials auto-loaded from slot directory]
```

--------------------------------

### Install Packages in Dockerfile

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/profile-system.md

Installs packages defined by the PACKAGES build argument in the Dockerfile. This layer is rebuilt if the PACKAGES argument changes.

```dockerfile
RUN apt-get update && apt-get install -y ${PACKAGES}
```

--------------------------------

### Brownfield Task Generation Example

Source: https://github.com/rchgrav/claudebox/blob/main/commands/BMad/tasks/create-brownfield-story.md

Example markdown structure for tasks and subtasks in a brownfield story, including analysis, implementation, verification, and testing.

```markdown
## Tasks / Subtasks

- [ ] Task 1: Analyze existing {{component/feature}} implementation
  - [ ] Review {{specific files}} for current patterns
  - [ ] Document integration points
  - [ ] Identify potential impacts

- [ ] Task 2: Implement {{new functionality}}
  - [ ] Follow pattern from {{example file}}
  - [ ] Integrate with {{existing component}}
  - [ ] Maintain compatibility with {{constraint}}

- [ ] Task 3: Verify existing functionality
  - [ ] Test {{existing feature 1}} still works
  - [ ] Verify {{integration point}} behavior unchanged
  - [ ] Check performance impact

- [ ] Task 4: Add tests
  - [ ] Unit tests following {{project test pattern}}
  - [ ] Integration test for {{integration point}}
  - [ ] Update existing tests if needed
```

--------------------------------

### Project Directory Structure

Source: https://github.com/rchgrav/claudebox/blob/main/CLAUDE.md

Illustrates the standard directory layout for the project, including directories for CLI entrypoints, libraries, tests, and documentation.

```text
project/
├── bin/          # thin CLI entrypoints that delegate work
├── lib/          # sourceable function libraries
├── test/         # Bats tests
├── docs/CLAUDE.md  ← YOU ARE HERE
└── shellcheckrc   # shared lint config
```

--------------------------------

### Claudebox CLI Argument Parsing Examples

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/cli-commands.md

Demonstrates how arguments are parsed into different buckets (flags, control, command, pass-through) based on the CLI's four-bucket architecture. Observe how different combinations of flags and commands are processed.

```bash
claudebox --verbose add python        # flags=[--verbose], cmd=add, pass=[python]
```

```bash
claudebox shell --model opus          # cmd=shell, pass=[--model, opus]
```

```bash
claudebox --enable-sudo shell --context 8k  # flags=[], control=[--enable-sudo], cmd=shell, pass=[--context, 8k]
```

--------------------------------

### Check Current Profiles and Packages

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/profile-system.md

Displays the currently active profiles and any extra packages installed for the project. This command helps in verifying the current state of the project's configuration.

```bash
claudebox add status
```

```bash
claudebox profile status
```

--------------------------------

### INI Configuration for Profiles

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/configuration.md

Defines development profiles and extra APT packages to install in a ClaudeBox project. Use `claudebox add`, `claudebox remove`, or `claudebox install` to modify.

```ini
[profiles]
core
python
rust

[packages]
htop
vim
tmux
```

--------------------------------

### Typical Task Management Workflow

Source: https://github.com/rchgrav/claudebox/blob/main/CLAUDE.md

This snippet demonstrates a common sequence of commands for managing a task using the Claudebox CLI. It covers identifying, detailing, starting, planning, breaking down, and completing tasks.

```bash
# 1 Identify work
backlog task list -s "To Do" --plain

# 2 Read details & documentation
backlog task 42 --plain
# Read also all documentation files in `backlog/docs/` directory.
# Read also all decision files in `backlog/decisions/` directory.

# 3 Start work: assign yourself & move column
backlog task edit 42 -a @{yourself} -s "In Progress"

# 4 Add implementation plan before starting
backlog task edit 42 --plan "1. Analyze current implementation
2. Identify bottlenecks
3. Refactor in phases"

# 5 Break work down if needed by creating subtasks or additional tasks
backlog task create "Refactor DB layer" -p 42 -a @{yourself} -d "Description" --ac "Tests pass,Performance improved"

# 6 Complete and mark Done
backlog task edit 42 -s Done --notes "Implemented GraphQL resolver with error handling and performance monitoring"
```

--------------------------------

### Troubleshooting: Creating More Slots

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/README.md

If no slots are available, run 'claudebox create' to add more.

```bash
claudebox create
```

--------------------------------

### Create a new task

Source: https://github.com/rchgrav/claudebox/blob/main/CLAUDE.md

Use this command to create a new task in the backlog. Provide a descriptive name for the task.

```bash
backlog task create "Add OAuth"
```

--------------------------------

### Determine Next Start Container

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/library-api.md

Finds the next available container slot to start by iterating through all slots and checking if they are running using `docker ps`. Skips non-existent slots.

```bash
slot=$(determine_next_start_container "$PROJECT_DIR")
# Returns: "12345678" or empty if none found
```

--------------------------------

### Auto MCP Setup Pseudo-code

Source: https://github.com/rchgrav/claudebox/blob/main/commands/adaptive.md

This pseudo-code illustrates how the orchestrator might automatically connect to MCP services like GitHub or databases based on detected needs. Ensure necessary tokens or credentials are provided.

```javascript
// Pseudo-code for auto MCP setup
const needs = analyzeTaskForIntegrations(task);
if (needs.github && !MCP.isConnected('github')) {
    MCP.connect('github', { token: GITHUB_TOKEN });
}
if (needs.database && !MCP.isConnected('database')) {
    MCP.connect('database', { credentials: DB_CREDENTIALS });
}
// ... etc.
```

--------------------------------

### Check Docker Installation

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/library-api.md

Verify if Docker is installed and operational by checking for the command's existence and successful execution of `docker info` and `docker ps`. Returns 0 on success, non-zero on failure.

```bash
if check_docker; then
    echo "Docker is ready"
fi
```

--------------------------------

### Open Project by Name or Hash

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/cli-commands.md

Opens a project by searching for a matching folder name or hash within `~/.claudebox/projects/`. It then changes the directory to the project and launches Claude within its container.

```bash
claudebox project website
```

```bash
claudebox project api_a1b2c3d4
```

--------------------------------

### fillbar(command)

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/library-api.md

Manages an animated progress bar. It can be started or stopped.

```APIDOC
## fillbar(command)

### Description
Show animated progress bar (infinite loop).

### Parameters
- **command** (string) - `start` (default) or `stop`

### Behavior
- Start: Launches background process showing animated bar
- Stop: Kills background, clears line, restores cursor

### Global variable
`$FILLBAR_PID` — PID of background process

### Example
```bash
fillbar              # Start progress
# ... long operation ...
fillbar stop         # Stop and clear
```
```

--------------------------------

### Claudebox CLI Entry Point

Source: https://github.com/rchgrav/claudebox/blob/main/_autodocs/README.md

Illustrates the command-line interface for Claudebox, detailing how user commands are parsed and processed to manage resources like Docker images and containers.

```bash
User runs: claudebox [options] [command] [args]
    ↓
main.sh (entry point)
    ├── Source all library modules (cli.sh, docker.sh, project.sh, etc.)
    ├── Parse arguments into four buckets (host flags, control flags, command, pass-through)
    ├── Determine what resources command needs (docker/image/none)
    ├── Initialize project directory if needed
    ├── Build/check Docker image (with layer caching)
    ├── Create slot if needed (CRC32-based naming)
    ├── Run container with mounts and security config
    └── → Pass control to Claude CLI or internal command handler
```

--------------------------------

### Counter Pruning Example

Source: https://github.com/rchgrav/claudebox/blob/main/docs/slot-management-system.md

Demonstrates the effect of counter pruning when slots are deleted.

```string
Before: Counter=5, Slots 1,2,3 exist (4,5 deleted)
After:  Counter=3
```

--------------------------------

### Usage Preview in PR Description

Source: https://github.com/rchgrav/claudebox/blob/main/claude/CLAUDE.md

For infrastructure-first PRs, include a usage preview in the PR description to show how the new code will be integrated in future PRs. This provides context for reviewers.

```markdown
## Usage Preview
This validation functionality will be used in future PRs to:
- PR 7: Wrap all service calls with `validate_input`
- PR 8: Add validation summaries for user feedback

```