bwc-cli - Build With Claude CLI

CLI tool for installing Claude Code subagents and commands from the community collection.

Installation

# Global installation (recommended)
npm install -g bwc-cli

# Or use directly with npx
npx bwc-cli@latest init

Quick Start

# Initialize user configuration (default)
bwc init

# Or initialize project configuration (team sharing)
bwc init --project

# Add a subagent (goes to project if project config exists)
bwc add --agent python-pro

# Add a command (goes to project if project config exists)
bwc add --command dockerize

# Browse and select interactively
bwc add

Commands

bwc init

Initialize bwc configuration.

# Initialize user configuration (default)
bwc init

# Initialize project-level configuration
bwc init --project

Options:

• -p, --project - Create project-level configuration
• -f, --force - Overwrite existing configuration

Important: When you initialize with --project, all subsequent bwc add commands will install to the project by default (.claude/agents/ and .claude/commands/)

bwc add

Add subagents or commands to your Claude Code setup.

# Add a specific subagent
bwc add --agent python-pro

# Add a specific command
bwc add --command dockerize

# Interactive mode (browse and select multiple items)
bwc add

# Force user-level installation even with project config
bwc add --agent python-pro --user

# Force project-level installation (requires project config)
bwc add --agent python-pro --project

Options:

• -a, --agent <name> - Add a specific subagent
• -c, --command <name> - Add a specific command
• -u, --user - Force user-level installation (when project config exists)
• -p, --project - Force project-level installation (requires project config)

Default Behavior:

• If ./bwc.config.json exists → installs to project (.claude/agents/, .claude/commands/)
• Otherwise → installs to user level (~/.claude/agents/, ~/.claude/commands/)

Interactive Mode Tips:

• Use SPACE to select/deselect items
• Use ENTER to confirm and install selected items
• You can select multiple items at once

bwc list

List available subagents and commands.

# List all items
bwc list

# List subagents only
bwc list --agents

# List commands only
bwc list --commands

# Filter by category
bwc list --category language-specialists

# Show only installed items
bwc list --installed

Options:

• -a, --agents - List subagents only
• -c, --commands - List commands only
• --category <category> - Filter by category
• --installed - Show only installed items

bwc search

Search for subagents and commands.

# Search both subagents and commands
bwc search python

# Search subagents only
bwc search python --agents

# Search commands only
bwc search docker --commands

Options:

• -a, --agents - Search subagents only
• -c, --commands - Search commands only

bwc install

Install all dependencies from configuration (perfect for team onboarding).

# Install all items listed in configuration
bwc install

This reads from either:

• Project configuration (./bwc.config.json) if it exists
• User configuration (~/.bwc/config.json) otherwise

bwc remove

Remove installed subagents, commands, or MCP servers.

# Remove a specific subagent
bwc remove --agent python-pro

# Remove a specific command
bwc remove --command dockerize

# Remove an MCP server
bwc remove --mcp postgres

# Force user-level removal (when project config exists)
bwc remove --agent python-pro --user

# Force project-level removal (requires project config)
bwc remove --agent python-pro --project

# Skip confirmation prompt
bwc remove --agent python-pro --yes

# Interactive mode
bwc remove

Options:

• -a, --agent <name> - Remove a specific subagent
• -c, --command <name> - Remove a specific command
• -m, --mcp <name> - Remove a specific MCP server
• -u, --user - Force user-level removal (when project config exists)
• -p, --project - Force project-level removal (requires project config)
• -y, --yes - Skip confirmation prompt

Default Behavior:

• If ./bwc.config.json exists → removes from project
• Otherwise → removes from user level
• Use --user to force user-level removal
• Use --project to force project-level removal

bwc status

Check the health of your BWC configuration and verify MCP server installations.

# Check basic configuration status
bwc status

# Verify MCP server installations (deep verification)
bwc status --verify-mcp

# Get machine-readable JSON output
bwc status --json

Options:

• --verify-mcp - Perform deep verification of MCP server installations
• --json - Output results in JSON format for scripting

Features:

• Shows configuration location and scope
• Lists installed subagents, commands, and MCP servers
• Verifies MCP server installations against actual Claude Code configuration
• Provides fix commands for missing or misconfigured servers
• Reminds about Docker gateway setup when needed

Example Output:

✓ BWC Configuration Status

Configuration: /path/to/bwc.config.json (project)

📦 Installed Items:
  Subagents: 3
  Commands: 2
  MCP Servers: 4

🔌 MCP Servers:
  ✓ postgres (Docker)
  ✓ github (Docker)
  ✓ linear-server (SSE)
  ⚠ supabase (Not installed)
    Fix: bwc add --mcp supabase --docker-mcp
    Note: Run 'bwc add --setup' to configure Docker gateway if needed

Configuration

User Configuration

Located at ~/.bwc/config.json (available across all your projects):

{
  "version": "1.0",
  "registry": "https://buildwithclaude.com/registry.json",
  "paths": {
    "subagents": "~/.claude/agents/",
    "commands": "~/.claude/commands/"
  },
  "installed": {
    "subagents": ["python-pro", "react-wizard"],
    "commands": ["dockerize", "test-runner"]
  }
}

Project Configuration

Located at ./bwc.config.json:

{
  "version": "1.0",
  "registry": "https://buildwithclaude.com/registry.json",
  "paths": {
    "subagents": ".claude/agents/",
    "commands": ".claude/commands/"
  },
  "installed": {
    "subagents": ["backend-architect", "database-admin"],
    "commands": ["api-tester", "dockerize"]
  }
}

Note: Add .claude/ to your .gitignore to avoid committing installed files.

Configuration Scope Behavior

When you initialize BWC with bwc init --project, it creates a project configuration that becomes the default for all installations:

# Initialize project configuration
bwc init --project

# These all install to PROJECT by default (./claude/agents/, ./claude/commands/)
bwc add --agent python-pro      # → ./claude/agents/python-pro.md
bwc add --command dockerize     # → ./claude/commands/dockerize.md

# MCP servers need explicit scope
bwc add --mcp postgres --scope project  # → ./bwc.config.json

# Override to install at user level
bwc add --agent golang-pro --user       # → ~/.claude/agents/golang-pro.md

# Force project level (when user config exists but you want project)
bwc add --agent rust-pro --project      # → .claude/agents/rust-pro.md

Use Cases

Team Onboarding

Share your Claude Code setup with your team:

# Initialize project configuration
bwc init --project

# Add project-specific subagents (automatically project-scoped)
bwc add --agent backend-architect
bwc add --agent database-admin
bwc add --command dockerize

# Commit configuration
git add bwc.config.json
git commit -m "Add Claude Code configuration"

# Team members install dependencies
git clone <repo>
bwc install

Bulk Installation

Add multiple items at once:

# Search for testing-related tools
bwc search test

# Add multiple items interactively
bwc add
# Select "Subagent"
# Select category or "All"
# Use SPACE to select multiple items
# Press ENTER to install all

CI/CD Integration

Automate Claude Code setup in your pipelines:

# .github/workflows/setup.yml
- name: Install bwc CLI
  run: npm install -g bwc-cli
  
- name: Install Claude dependencies
  run: bwc install

MCP Servers

🔌 Connect Claude to External Tools

BWC CLI supports MCP (Model Context Protocol) servers through two providers:

• Docker MCP Gateway: Secure containerized servers (100+ available)
• Claude CLI: Remote servers via SSE/HTTP for cloud services

Prerequisites

• For Docker MCP: Docker Desktop - Download from docker.com/products/docker-desktop
• For Remote MCP: Claude CLI installed (npm install -g @anthropic/claude-cli)

Quick Start

Docker MCP Servers (Local/Containerized)

# Setup Docker gateway (one-time)
bwc add --setup

# Add a Docker MCP server
bwc add --mcp postgres --docker-mcp

# Add with specific scope
bwc add --mcp postgres --docker-mcp --scope project

Remote MCP Servers (SSE/HTTP)

# Add an SSE server
bwc add --mcp linear-server --transport sse --url https://mcp.linear.app/sse --scope project

# Add an HTTP server with authentication
bwc add --mcp api-server --transport http --url https://api.example.com/mcp \
  --header "Authorization: Bearer token" --scope project

# Add with environment variables
bwc add --mcp custom-server --transport stdio --env API_KEY=secret --scope user

Interactive Mode

# Browse and select servers interactively
bwc add
# Choose "MCP Server"
# Select provider (Docker or Remote)
# Configure as prompted

Installation Scopes

Local Scope (Default)

• Location: Claude Code local configuration
• Availability: Current machine only
• Use Case: Personal experimentation
• Sharing: Not shared with team

User Scope

• Location: ~/.bwc/config.json and Claude Code user config
• Availability: All your projects on this machine
• Use Case: Personal tools across projects
• Sharing: Not shared with team

Project Scope (Team Sharing)

• Location: ./bwc.config.json and ./.mcp.json
• Availability: Current project for all team members
• Use Case: Team collaboration
• Sharing: Committed to version control

# Local scope (default)
bwc add --mcp postgres --docker-mcp

# User scope (all your projects)
bwc add --mcp postgres --docker-mcp --scope user

# Project scope (team sharing)
bwc add --mcp postgres --docker-mcp --scope project

# Remote servers also support all scopes
bwc add --mcp api-server --transport http --url https://api.example.com --scope project

Important for Team Sharing:

• Project scope servers are saved to .mcp.json for Claude Code
• Docker servers use the gateway and are NOT in .mcp.json
• SSE/HTTP servers ARE saved in .mcp.json with "type" field
• Commit both bwc.config.json and .mcp.json to share with team

Team Collaboration Example

# Team lead sets up project MCP servers
bwc init --project

# Add Docker MCP servers
bwc add --mcp postgres --docker-mcp --scope project
bwc add --mcp github --docker-mcp --scope project

# Add remote MCP server
bwc add --mcp linear-server --transport sse \
  --url https://mcp.linear.app/sse --scope project

# Commit configuration
git add bwc.config.json .mcp.json
git commit -m "Add team MCP servers"

# Team members clone and install
git clone <repo>
bwc install  # Installs all configured MCP servers

# Verify installations
bwc status --verify-mcp

Provider Comparison

Docker MCP Gateway

• 🔒 Container Isolation: Complete system protection
• 🔑 Secure Secrets: Docker manages all API keys
• ✅ Verified Images: All servers signed by Docker
• 🌐 Single Gateway: One secure endpoint for all servers
• 📦 100+ Servers: Large catalog of containerized servers

Remote MCP (Claude CLI)

• ☁️ Cloud Services: Direct connection to cloud APIs
• 🔐 Custom Auth: Support for API keys and headers
• 🌍 SSE/HTTP: Real-time and REST API connections
• 🤝 Team Sharing: Easy sharing via .mcp.json
• ⚡ No Docker Required: Works without Docker Desktop

MCP Commands

# Add MCP servers
bwc add --mcp <name> [options]

# Remove MCP servers
bwc remove --mcp <name>

# Check status and verify installations
bwc status               # Basic status
bwc status --verify-mcp  # Deep verification with fix suggestions

# List installed servers
bwc list --mcps

# Setup Docker gateway
bwc add --setup

Examples

Adding a Docker MCP Server

$ bwc add --mcp postgres --docker-mcp --scope project
✓ Enabled postgres in Docker MCP Gateway
✓ Server available through Docker gateway
✓ Configuration saved to project

Adding a Remote SSE Server

$ bwc add --mcp linear-server --transport sse \
    --url https://mcp.linear.app/sse --scope project
✓ Configured linear-server in Claude Code
✓ Added to .mcp.json for team sharing

Verifying Installations

$ bwc status --verify-mcp
✓ BWC Configuration Status

🔌 MCP Server Verification:
  ✓ postgres (Docker) - Installed
  ✓ linear-server (SSE) - Installed in .mcp.json
  ⚠ github (Docker) - Not installed
    Fix: bwc add --mcp github --docker-mcp
    Note: Run 'bwc add --setup' if Docker gateway not configured

Popular MCP Servers

Docker MCP Servers

• postgres: PostgreSQL database operations
• github: GitHub API integration
• elasticsearch: Search and analytics
• redis: Caching and data store
• mongodb: NoSQL database

Remote MCP Servers (SSE/HTTP)

• linear-server: Linear issue tracking (SSE)
• supabase: Supabase backend services (HTTP)
• stripe: Payment processing (HTTP)
• slack: Team communication (HTTP)
• notion: Knowledge management (HTTP)

View all servers at buildwithclaude.com/mcp-servers

Categories

Subagent Categories

• development-architecture - Backend, frontend, mobile, API design
• language-specialists - Language-specific expertise (Python, Go, Rust, etc.)
• infrastructure-operations - DevOps, cloud, deployment, databases
• quality-security - Code review, security, testing, performance
• data-ai - Data science, ML/AI engineering, analytics
• specialized-domains - Domain-specific tools (payments, blockchain, etc.)
• crypto-trading - Cryptocurrency and DeFi applications

Command Categories

• ci-deployment - CI/CD and deployment commands
• code-analysis-testing - Code quality and testing commands
• context-loading-priming - Context and priming commands
• documentation-changelogs - Documentation commands
• project-task-management - Project management commands
• version-control-git - Git and version control commands
• miscellaneous - Other specialized commands

Proxy Support

BWC CLI automatically respects standard proxy environment variables for all network requests:

Environment Variables

# HTTP proxy
export HTTP_PROXY=http://proxy.example.com:8080
export http_proxy=http://proxy.example.com:8080

# HTTPS proxy (recommended)
export HTTPS_PROXY=https://proxy.example.com:8080
export https_proxy=https://proxy.example.com:8080

# No proxy list (comma-separated)
export NO_PROXY=localhost,127.0.0.1,example.com,*.internal.net
export no_proxy=localhost,127.0.0.1,example.com,*.internal.net

# Custom CA certificates (for corporate proxies)
export NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.crt

Usage Examples

# Use with proxy
HTTPS_PROXY=http://proxy.example.com:8080 bwc add --command all-tools

# Bypass proxy for specific domains
NO_PROXY=localhost,github.com bwc list

# With authentication
HTTPS_PROXY=http://username:[email protected]:8080 bwc add

Features

• Automatic Detection: BWC CLI automatically detects and uses proxy settings from environment variables
• NO_PROXY Support: Bypass proxy for specific domains using the NO_PROXY environment variable
• Authentication: Supports basic authentication in proxy URLs
• SSL Certificates: Respects NODE_EXTRA_CA_CERTS for custom certificate authorities
• Fallback: Uses HTTP_PROXY for HTTPS requests if HTTPS_PROXY is not set

Debugging Proxy Issues

If you encounter connection issues behind a proxy:

1. Verify proxy settings:

   echo $HTTPS_PROXY
   echo $NO_PROXY

2. Test with verbose output:

   HTTPS_PROXY=http://proxy:8080 bwc list --mcps

   Look for the "Using proxy:" message to confirm proxy detection.

3. Check certificate issues:

   # For self-signed certificates
   export NODE_TLS_REJECT_UNAUTHORIZED=0  # Only for testing!
      
   # Better: Add your CA certificate
   export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.crt

Troubleshooting

Configuration not found

Run bwc init to create configuration.

Failed to fetch registry

Check your internet connection. The CLI needs access to buildwithclaude.com.

Permission denied

On macOS/Linux, you may need to use sudo npm install -g bwc-cli.

Interactive mode not selecting

Use SPACE to select items (not Enter). Selected items show a ● marker. Press ENTER only to confirm.

Contributing

Contributions are welcome! Please visit our GitHub repository to submit pull requests for new subagents, commands, or MCP servers.

Development

# Clone the repository
git clone https://github.com/davepoon/claude-code-subagents-collection.git
cd claude-code-subagents-collection/packages/bwc-cli

# Install dependencies
npm install

# Build the CLI
npm run build

# Run in development mode
npm run dev

# Link for local testing
npm link

Links

• Website: buildwithclaude.com
• Documentation: buildwithclaude.com/docs/cli
• GitHub: github.com/davepoon/claude-code-subagents-collection
• Issues: Report bugs or suggest features

License

MIT © Dave Poon