Getting Started with CCO

Install, configure, and run your first task with the Codified Orchestrator.

Installation

Requirements

Python 3.10+

CCO requires Python 3.10 or higher with pip package manager.

Verify your Python version:

bash 
python3 --version

Install via pip

Install CCO in development mode with all dependencies:

bash 
pip install -e ".[dev]"
ℹ️

Using -e (editable mode) allows you to run cco from anywhere while keeping the package linked to this source directory.

Verify Installation

Confirm CCO is installed correctly:

bash 
cco --version

You should see output like:

bash 
cco, version 1.0.0
✓

Installation successful! Continue to Configuration to set up your API endpoints.

Configuration

CCO uses a profile-based configuration system. Initialize a profile with your preferred endpoints:

Initialize Configuration

bash 
cco config init --profile direct-minimax
ℹ️

The direct-minimax profile configures CCO to use MiniMax API as the primary endpoint. You can create custom profiles for different providers.

Config File Location

CCO stores its configuration at:

bash 
~/.codified-orchestrator/config.yaml

Endpoint Architecture

CCO uses a three-tier endpoint model:

Primary Endpoint

Main LLM provider for task execution

The primary endpoint handles most tasks. Configure this based on your preferred model provider (MiniMax, Ollama, etc.).

Fallback Endpoint

Backup provider for reliability

When the primary endpoint is unavailable or returns an error, CCO automatically falls back to this endpoint.

Escalation Endpoint

Human review trigger

For complex or sensitive tasks that exceed the model's capabilities, CCO can escalate to a human reviewer.

View your current configuration:

bash 
cco config show

Your First Task

1. Prepare a Repository

You can use an existing repository or create a test repository:

bash 
# Create a test repository
mkdir my-test-repo && cd my-test-repo
git init

# Or use an existing repository
# cco doctor --repo /path/to/existing/repo

2. Verify Setup with Doctor

Run the doctor command to verify your setup and check the repository:

bash 
cco doctor --repo /path/to/your/repo

Doctor checks:

  • Configuration validity and endpoint connectivity
  • Repository structure and required files
  • Memory store status
  • Agent availability
ℹ️

For JSON output (useful for automation): cco doctor --repo /path/to/repo --json

3. Plan a Task

Before executing, preview what CCO will do with the plan command:

bash 
cco plan --repo /path/to/repo --task "Inspect context loading"

Plan shows:

  • Selected agent(s) for the task
  • Relevant context that will be loaded
  • Expected changes or actions
  • Estimated complexity

4. Execute with Guardrails

Execute the task with mutation guardrails enabled:

bash 
cco task --repo /path/to/repo --task "Inspect context loading" --guarded

Understanding --guarded Mode

What --guarded Does

Mutation guardrails for safe task execution

The --guarded flag enables safety checks that:

  • Pre-flight checks - Validate environment before changes
  • Branch isolation - Create a dedicated branch for changes
  • Scope limiting - Restrict file modifications to task-relevant paths
  • Confirmation prompts - Ask for explicit approval before destructive actions
  • Rollback capability - Abort and revert if issues are detected
⚠️

Always use --guarded for production repositories. Omit it only for exploratory tasks where you want unrestricted access.

Repository Setup

For CCO to work effectively, your repository needs specific files that provide context about your project.

Required Files

AGENTS.md Required

Agent definitions and project-specific instructions

This file defines:

  • Available agents and their capabilities
  • Agent prompting conventions
  • Trigger patterns for auto-selection
  • Project-specific agent customizations

Place at repository root: /AGENTS.md

.context/architecture.md Required

System design and component flow

Documents the technical architecture of your project, including:

  • Component diagram and relationships
  • Data flow patterns
  • Key design decisions
  • Technology stack overview

Place in: /.context/architecture.md

.context/decisions.md Required

Architectural decision log (ADRs)

Records significant decisions made during development:

  • Why certain approaches were chosen
  • Alternatives considered and rejected
  • Consequences of major changes
  • Historical context for legacy code

Place in: /.context/decisions.md

.context/known-issues.md Required

Recurring bugs and mitigations

Documents known problems and workarounds:

  • Current bugs and their status
  • Known edge cases
  • Available workarounds
  • Things to avoid

Place in: /.context/known-issues.md

.context/deployment.md Required

Installation and operation notes

Contains deployment and operations information:

  • Environment setup requirements
  • Configuration parameters
  • Deployment procedures
  • Operational runbooks

Place in: /.context/deployment.md

Minimal Repository Structure

A minimal CCO-enabled repository looks like:

bash 
your-repo/
├── AGENTS.md                    # Agent definitions
├── .context/
│   ├── architecture.md         # System architecture
│   ├── decisions.md             # Architectural decisions
│   ├── known-issues.md         # Known bugs and issues
│   └── deployment.md            # Deployment guide
├── src/                         # Your source code
├── tests/                       # Your tests
└── README.md                    # Project documentation

Using the Sample Repository

CCO includes a sample repository for testing:

bash 
cco doctor --repo tests/fixtures/sample_repo
✓

You're now ready to use CCO! Continue to the CLI Reference to explore all available commands.

↑↓ Navigate Enter Select Esc Close