Installation

System Requirements

Before installing CCCC, ensure your system meets the following requirements:

Required Software

• Python 3.9 or higher

  • Check version: python3 --version
  • Download from python.org

• tmux (terminal multiplexer)

  • macOS: brew install tmux
  • Ubuntu/Debian: sudo apt-get install tmux
  • Fedora: sudo dnf install tmux
  • Windows: Use WSL (Windows Subsystem for Linux)

• git (version control)

  • Check version: git --version
  • Download from git-scm.com

AI Service Subscriptions

CCCC leverages your existing AI subscriptions. You'll need at least one:

• Claude (Anthropic) - Recommended for primary agent
• ChatGPT (OpenAI) - Alternative or secondary agent
• Gemini (Google) - Optional auxiliary agent

No API keys required—CCCC uses your Pro/Plus/Advanced subscriptions directly.

Operating System Support

• macOS: Full support (10.14+)
• Linux: Full support (Ubuntu 20.04+, Debian 10+, Fedora 32+)
• Windows: Via WSL2 (Windows Subsystem for Linux)

Installation Methods

Method 1: Using pipx (Recommended)

pipx installs Python applications in isolated environments:

# Install pipx if not already installed
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# Install CCCC
pipx install cccc-pair

Benefits:

• Isolated environment prevents conflicts
• Automatic PATH configuration
• Easy updates: pipx upgrade cccc-pair
• Clean uninstall: pipx uninstall cccc-pair

Method 2: Using pip in Virtual Environment

For more control over the environment:

# Create virtual environment
python3 -m venv cccc-env

# Activate virtual environment
source cccc-env/bin/activate  # macOS/Linux
# OR
cccc-env\Scripts\activate  # Windows

# Install CCCC
pip install cccc-pair

Method 3: Development Installation

For contributors or those wanting the latest features:

# Clone repository
git clone https://github.com/ChesterRa/cccc.git
cd cccc

# Create virtual environment
python3 -m venv v
source v/bin/activate

# Install in editable mode
pip install -e .

Post-Installation Setup

Verify Installation

Check that CCCC is properly installed:

cccc --version

Expected output: cccc version X.Y.Z

Run System Check

Validate your environment:

cccc doctor

This command checks:

• ✅ Python version compatibility
• ✅ tmux availability
• ✅ git installation
• ✅ Required dependencies
• ✅ Configuration files

Example output:

✅ Python 3.11.5 detected
✅ tmux 3.3a found
✅ git 2.42.0 available
✅ All dependencies installed
⚠️  No repository initialized (run 'cccc init' in a repo)

Initialize in Repository

Navigate to your project and initialize:

cd /path/to/your/repository
cccc init

This creates:

• .cccc/ directory with configuration
• POR.md (Plan of Record)
• SUBPOR.md (Sub-Plan of Record)
• .gitignore entries for CCCC artifacts

Configuration Files

After initialization, you'll have:

.cccc/config.yaml

Main configuration file:

version: 1.0
agents:
  primary_a: claude-code
  primary_b: codex-cli
  auxiliary: gemini-cli
tmux:
  session_name: cccc-orchestrator
  window_layout: tiled
git:
  auto_commit: true
  commit_prefix: "[CCCC]"

POR.md

Strategic tracking board:

# Plan of Record

## Current Goals
- [Add goal here]

## Milestones
- [ ] Milestone 1
- [ ] Milestone 2

## Strategic Decisions
[Decisions will be logged here by agents]

SUBPOR.md

Per-task tracking:

# Sub-Plan of Record

## Current Task
[Task description]

## Evidence Trail
[Agent debates and decisions]

## Progress
- [ ] Step 1
- [ ] Step 2

Troubleshooting

Python Version Issues

If cccc doctor reports Python version issues:

# Check current Python version
python3 --version

# If using pyenv
pyenv install 3.11.5
pyenv global 3.11.5

# Reinstall CCCC
pipx reinstall cccc-pair

tmux Not Found

macOS:

brew install tmux

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install tmux

Windows: Enable WSL2 and install Ubuntu, then install tmux within WSL.

Permission Errors

If installation fails with permission errors:

# Use pipx (recommended)
pipx install cccc-pair

# Or install for user only
pip install --user cccc-pair

PATH Issues

If cccc command not found after installation:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

# Reload shell
source ~/.bashrc  # or source ~/.zshrc

Updating CCCC

Using pipx

pipx upgrade cccc-pair

Using pip

pip install --upgrade cccc-pair

Development Installation

cd /path/to/cccc
git pull origin main
pip install -e . --upgrade

Uninstalling

Using pipx

pipx uninstall cccc-pair

Using pip

pip uninstall cccc-pair

Clean Up Configuration

# Remove CCCC directory (optional)
rm -rf ~/.cccc

# Remove repository files (if desired)
cd /path/to/repo
rm -rf .cccc POR.md SUBPOR.md

Next Steps

Now that CCCC is installed:

• Read Configuration to customize your setup
• Learn Usage patterns and workflows
• Review Getting Started for quick start guide

Need Help?

• Check GitHub Issues
• Join community discussions
• Review troubleshooting documentation