CLI Quick Start

Get started with CCCC using the command line.

Commands that accept --group resolve it in this order: the explicit option, the Actor's CCCC_GROUP_ID environment, then the active Group selected with cccc use. Messaging uses --by, then CCCC_ACTOR_ID, then user. An Actor therefore keeps its own Group when another session changes the active Group.

Step 1: Navigate to Your Project

cd /path/to/your/project

Step 2: Create a Working Group

cccc attach .

This binds the current directory as a "scope" and creates a working group.

Step 3: Prepare the Runtime Integration

cccc setup --runtime claude   # or codex, droid, grok, kimi

This prepares or reports the runtime's CCCC MCP integration. Direct Claude Code, Codex, Grok Build, and OpenCode managed sessions receive their scoped MCP entry automatically when CCCC starts them; other runtimes may use persistent or prompt-assisted setup.

Step 4: Add Your First Agent

cccc actor add assistant --runtime claude

The first enabled actor automatically becomes the "foreman" (coordinator).

Step 5: Start the Agent

cccc group start

Or start a specific agent:

cccc actor start assistant

Step 6: Send a Message

cccc send "Hello! Please introduce yourself."

Step 7: View Responses

Watch the ledger in real-time:

cccc tail -f

Or check inbox:

cccc inbox --actor-id assistant

Adding More Agents

Add a second agent:

cccc actor add reviewer --runtime codex
cccc actor start reviewer

Send to specific agents:

cccc send "Please implement the feature" --to assistant
cccc send "Please review the code" --to reviewer
cccc send "Please coordinate the next step" --to @foreman
cccc send "Team-wide constraint: pause deploys until CI is green" --to @all

Use task-backed delegation when the work should survive chat context switches and needs an owner, outcome, or completion evidence:

cccc tracked-send "Please implement the feature and reply with validation evidence." \
  --to assistant \
  --title "Implement feature" \
  --outcome "Feature is implemented and validation evidence is reported"

Reply to Messages

# Find the event ID from cccc tail
cccc reply evt_abc123 "Thanks, that looks good!"
cccc reply evt_abc123 "Non-urgent follow-up" --mode mail

Common Commands

For other instances, use cccc connect to discover accessible Groups, then cccc send --dst-instance ... --dst-group .... Reply with the incoming local Event ID. See Agent collaboration for the complete discovery, send and reply flow, including Direct connections.

Group Management

cccc groups              # List all groups
cccc use <group_id>      # Switch group
cccc active              # Show active group
cccc group show <group_id> # Show group metadata
cccc group start         # Start all agents
cccc group stop          # Stop all agents

Actor Management

cccc actor list                    # List actors
cccc actor add <id> --runtime <r>  # Add actor
cccc actor start <id>              # Start actor
cccc actor stop <id>               # Stop actor
cccc actor restart <id>            # Restart actor
cccc actor remove <id>             # Remove actor

Messaging

cccc send "message"                # No --to: default recipient policy applies (default: foreman)
cccc send "msg" --to assistant     # To specific actor
cccc send "msg" --to @foreman      # Ask the coordinator
cccc send "msg" --to @all          # Explicit broadcast, not default task dispatch
cccc tracked-send "work" --to assistant --title "Task title" --outcome "Done criterion"
cccc reply <event_id> "response"   # Reply to message
cccc inbox --actor-id assistant    # Read unread Mail for one actor
cccc tail -n 50                    # Recent events
cccc tail -f                       # Follow events

Daemon Control

cccc daemon status    # Check status
cccc daemon start     # Start daemon
cccc daemon stop      # Stop daemon

Start Web UI (Optional)

While using CLI, you can also open the Web UI:

cccc   # Starts daemon + Web UI

Or just the Web UI (if daemon is already running):

cccc web

Access at http://127.0.0.1:8848/

Environment Variables

Variable	Default	Description
CCCC_HOME	~/.cccc	Runtime directory
CCCC_WEB_PORT	8848	Web UI port
CCCC_WEB_READY_TIMEOUT_SECONDS	10	Web startup readiness timeout for slower machines
CCCC_LOG_LEVEL	INFO	Log verbosity

Example Workflow

# Setup
cd ~/projects/my-app
cccc attach .
cccc setup --runtime claude
cccc actor add dev --runtime claude

# Work
cccc group start
cccc send "Please plan the smallest safe authentication task." --to @foreman
cccc tracked-send "Please implement the first authentication task and reply with validation evidence." \
  --to dev \
  --title "Implement first authentication slice" \
  --outcome "Implementation is complete and validation evidence is reported"

# Monitor
cccc tail -f

# Interact
cccc reply evt_123 "Use JWT tokens please"
cccc send "What's the progress?" --to dev

# Cleanup
cccc group stop

Troubleshooting

Daemon not starting?

cccc daemon status
cccc daemon stop      # Stop any stuck instance
cccc daemon start

Agent not responding?

# Check agent status
cccc actor list

# Restart the agent
cccc actor restart <actor_id>

# Check MCP setup
cccc setup --runtime <name>

Can't find my group?

# List all groups
cccc groups

# Re-attach if needed
cd /path/to/project
cccc attach .

Next Steps

• Workflows - Learn collaboration patterns
• CLI Reference - Complete command reference
• IM Bridge - Set up mobile access