Usage Guide

Basic Commands

Core Commands

# Initialize CCCC in repository
cccc init

# Verify environment and configuration
cccc doctor

# Start orchestration
cccc run

# Stop orchestration
cccc stop

# Check status
cccc status

# View logs
cccc logs

# Show version
cccc --version

Session Management

# Attach to running session
cccc attach

# Detach from session (inside tmux)
# Press: Ctrl+B, then D

# List active sessions
cccc ps

# Kill specific session
cccc kill <session-id>

Starting Your First Session

Step-by-Step Workflow

1. Navigate to Repository

cd /path/to/your/project

2. Initialize CCCC

cccc init

This creates:

• .cccc/config.yaml
• POR.md
• SUBPOR.md

3. Review and Edit POR.md

Open POR.md and define your goals:

# Plan of Record

## Current Goals
- Implement user authentication system
- Add password reset functionality
- Write comprehensive tests

## Milestones
- [ ] User model and database schema
- [ ] Login/logout endpoints
- [ ] Password reset flow
- [ ] Test coverage >80%

## Strategic Decisions
[Agents will log decisions here]

4. Start Orchestration

cccc run

5. Monitor Progress

Option A: Watch POR.md/SUBPOR.md files update in real-time

Option B: Attach to session

cccc attach

Option C: Use IM integration (if configured)

• Telegram: Receive updates on mobile
• Slack: Monitor in team channel

6. Review Changes

git log --oneline | head -10
git diff HEAD~5

Working with IM Integration

Telegram Commands

Once configured, send commands to your CCCC bot:

/status          - Get current status
/pause           - Pause orchestration
/resume          - Resume orchestration
/goals           - View current goals
/progress        - Check progress
/recent          - Show recent commits
/por             - View POR summary
/help            - List all commands

Remote Control

From your phone:

1. Open Telegram
2. Find your CCCC bot
3. Send: /status
4. Review progress and agent debates
5. Adjust goals if needed: /set goal "New goal"

From Slack: Post in configured channel:

@cccc status
@cccc pause "Taking lunch break"
@cccc resume

Common Workflows

Workflow 1: Feature Development

# 1. Create feature branch
git checkout -b feature/user-auth

# 2. Initialize CCCC
cccc init

# 3. Define goals in POR.md
# - Implement user authentication
# - Add JWT tokens
# - Write integration tests

# 4. Start orchestration
cccc run

# 5. Monitor via IM or attach
cccc attach

# 6. Review and merge when complete
git checkout main
git merge feature/user-auth

Workflow 2: Bug Fixing

# 1. Document bug in POR.md
echo "## Current Bug: Login fails on special characters" >> POR.md

# 2. Start targeted session
cccc run --focus "Fix login special character bug"

# 3. Monitor agent collaboration
cccc logs --follow

# 4. Review fix
git diff
git show HEAD

# 5. Deploy if satisfied
./deploy.sh

Workflow 3: Refactoring

# 1. Define refactoring goal
cccc set-goal "Refactor auth module for better testability"

# 2. Run with high evidence verbosity
cccc run --evidence-level high

# 3. Review agent debates
cat SUBPOR.md

# 4. Approve changes incrementally
cccc approve-step 1
cccc approve-step 2
# ...

Workflow 4: Documentation

# 1. Configure for documentation task
cccc set-goal "Write comprehensive API documentation"

# 2. Use auxiliary agent for completeness
cccc run --with-auxiliary

# 3. Monitor documentation generation
watch -n 5 'ls docs/*.md'

# 4. Review and publish
mkdocs build
mkdocs gh-deploy

Best Practices

1. Clear Goal Definition

Good:

## Goals
- Implement user registration with email verification
- Ensure password strength validation (min 8 chars, 1 uppercase, 1 number)
- Add rate limiting (max 5 attempts per minute)
- Write unit tests for all edge cases

Bad:

## Goals
- Add user stuff
- Make it work
- Tests maybe

2. Granular Milestones

Break large tasks into checkpoints:

## Milestones
- [ ] Database schema for users table
- [ ] User model with validation
- [ ] Registration endpoint
- [ ] Email verification service
- [ ] Password hashing utility
- [ ] Rate limiting middleware
- [ ] Unit tests for user model
- [ ] Integration tests for registration

3. Regular POR Reviews

Check POR.md frequently to ensure agents stay on track:

# Watch POR.md for updates
watch -n 10 cat POR.md

# Or use git to track changes
git diff POR.md

4. Incremental Commits

CCCC makes small commits—review them regularly:

# Review recent commits
git log --oneline -10

# Check individual commit
git show <commit-hash>

# Revert if needed
git revert <commit-hash>

5. Evidence Review

Examine agent reasoning in SUBPOR.md:

# View full debate
cat SUBPOR.md

# Search for specific decision
grep -A 10 "Authentication approach" SUBPOR.md

Advanced Usage

Custom Task Instructions

Provide detailed instructions for complex tasks:

cccc run --instructions "Implement OAuth2 flow following RFC 6749.
Use Authorization Code Grant.
Store tokens in secure HTTP-only cookies.
Add PKCE for public clients.
Write integration tests covering all grant types."

Multi-Repository Orchestration

Run CCCC across multiple related repositories:

# Project structure
/workspace
  /frontend
  /backend
  /shared-lib

# Initialize each
cd /workspace/frontend && cccc init
cd /workspace/backend && cccc init
cd /workspace/shared-lib && cccc init

# Run coordinated session
cccc run-multi --repos frontend,backend,shared-lib \
               --sync-por \
               --goal "Implement new API endpoint end-to-end"

Checkpointing and Resume

Leverage context management for long-running tasks:

# Start long-running task
cccc run --goal "Migrate entire codebase to TypeScript"

# Checkpoint manually
cccc checkpoint save "Completed 20% of migration"

# Stop for the day
cccc stop

# Resume next day
cccc resume --from-checkpoint latest

Agent Override

Temporarily adjust agent behavior:

# Use more creative approach
cccc run --primary-a-temp 0.9 --primary-b-temp 0.9

# Be more conservative
cccc run --primary-a-temp 0.3 --primary-b-temp 0.3

# Increase consensus threshold
cccc run --consensus 0.95

Dry Run Mode

Test orchestration without making changes:

cccc run --dry-run

# Review proposed changes
cat .cccc/dry-run-preview.md

# Apply if satisfied
cccc apply-dry-run

Monitoring and Debugging

Real-Time Monitoring

Watch logs:

cccc logs --follow

Monitor specific agent:

cccc logs --agent primary-a --follow

Filter by level:

cccc logs --level ERROR

Debugging Issues

Check agent status:

cccc status --detailed

View agent conversation:

cccc debug --show-conversation

Trace specific decision:

cccc trace "Why was approach X chosen over Y?"

Health check:

cccc doctor --verbose

Performance Optimization

Speed Up Convergence

# Reduce debate rounds
cccc run --max-rounds 3

# Lower consensus threshold
cccc run --consensus 0.7

# Disable auxiliary agent
cccc run --no-auxiliary

Reduce Resource Usage

# Limit tokens per agent
cccc run --max-tokens 2000

# Reduce concurrent agents
cccc run --max-concurrent 2

# Use smaller context window
cccc run --context-size 10000

Troubleshooting

Agents Not Reaching Consensus

# View debate details
cccc debug --show-debate

# Manually resolve
cccc resolve --force-consensus --approach 1

# Or restart with clearer goal
cccc stop
# Edit POR.md with more specific instructions
cccc run

Session Hangs

# Check if agents are stuck
cccc status

# Force restart agent
cccc restart-agent primary-a

# Kill and restart session
cccc stop --force
cccc run

Context Drift

# Refresh context
cccc refresh-context

# Reset to checkpoint
cccc reset --to-checkpoint <checkpoint-id>

# Reinitialize if needed
cccc init --force

Tips and Tricks

1. Use Git Branches

Isolate CCCC work in branches for easy rollback:

git checkout -b cccc/feature-experiment
cccc run
# Review changes, merge if good

2. Template POR Files

Create templates for common tasks:

cp POR.md .cccc/templates/feature-template.md
# Reuse for future features

3. Automate with Git Hooks

Add pre-commit hook to validate CCCC changes:

#!/bin/bash
# .git/hooks/pre-commit
if grep -q "CCCC" POR.md; then
  cccc validate-changes
fi

4. Integrate with CI/CD

Run CCCC in CI pipeline:

# .github/workflows/cccc.yml
- name: Run CCCC Tests
  run: |
    cccc run --goal "Add tests for new features"
    cccc wait-for-completion
    pytest

Next Steps

• Review Fundamentals for core concepts
• Explore Configuration for advanced settings
• Check Getting Started for quick reference

Need Help?

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