📚 OCCode Documentation

🎯 Overview

OCCode is a powerful AI-powered coding assistant that runs directly in your terminal. It combines the capabilities of multiple AI models with advanced features like convergence orchestration, model profiles, and intelligent context management.

🚀 Getting Started

Installation

Download OCCode from opencan.ai/downloads (account required), then install:

# Extract the archive (Linux/macOS)
tar xzf occode-0.1.0-linux-x64.tar.gz
sudo mv occode /usr/local/bin/

# Activate with your license key
occode activate --key YOUR-LICENSE-KEY

# Verify installation
occode --version

First Run

# Set your API key
export ANTHROPIC_API_KEY="your-key-here"

# Start OCCode
occode

Basic Usage

# Ask a question
What is recursion?

# Generate code
write a binary search function in TypeScript

# Add files to context
/context src/main.ts

# Get help
/help

👤 Model Profiles NEW

Model Profiles let you create named configurations for different AI models and switch between them instantly using prefix shortcuts.

Creating Profiles

From Built-in Templates

/profile template fast      # Claude Haiku - quick answers
/profile template power     # Claude Opus - complex tasks
/profile template creative  # High temperature Sonnet
/profile template gpt       # GPT-4 Turbo
/profile template local     # Ollama (offline)

Interactive Creation

/profile create myprofile

You'll be prompted for:

• Provider (anthropic, openai, google, etc.)
• Model (sonnet, gpt4o, etc.)
• Temperature (0.0-1.0)
• Max tokens
• Description
• Prefix trigger (optional)

Using Profiles

Activate a Profile

/profile fast     # Switch to fast profile
/profile power    # Switch to power profile
/profile off      # Deactivate (use global config)

Prefix Shortcuts

Set a prefix trigger to temporarily use a profile for a single message:

# Set prefix for a profile
/profile prefix fast quick:
/profile prefix power think:

# Use in conversation
quick: what is recursion?
think: design a distributed cache system

Managing Profiles

Built-in Templates

⚡ Convergence Engine NEW

The Convergence Engine runs multiple AI models in parallel and combines their outputs using the Mixture-of-Agents pattern for higher quality results.

How It Works

1. Generate - Multiple models work on the task simultaneously
2. Synthesize - An aggregator model combines the best parts
3. Return - A single, higher-quality response

Quick Start with Presets

# View available presets
/converge preset

# Apply a preset
/converge preset duo-merge

# Enable convergence
/converge on

# Your messages now use convergence
write a binary search function

# Disable when done
/converge off

Built-in Presets

Convergence Strategies

Merge Strategy (MoA)

All participant models generate responses in parallel, then an aggregator synthesizes the best parts.

Best for: Code generation, complex explanations, creative tasks

Vote Strategy

All models generate responses, then each votes for the best (not their own).

Best for: Tasks with objective correct answers, choosing between options

Debate Strategy

Multi-round critique and refinement - models critique each other, then revise their responses.

Best for: Important decisions, thorough analysis, exploring trade-offs

Review Strategy

Pair programming workflow - Model A generates, Model B reviews, Model A revises.

Best for: Code quality, catching bugs, cost-effective quality boost

Custom Configuration

Cost Optimization Tips

1. Use for Important Tasks: Reserve convergence for critical code or complex problems
2. Review Strategy: Most cost-effective (only 3-4 API calls)
3. Disable show: Viewing individual outputs doesn't affect quality
4. Local Models: Use local-merge preset for zero API costs (requires Ollama)
5. Duo vs Trio: duo-merge is 33% cheaper than trio-merge

📖 Model Catalog NEW

The Model Catalog is a centralized registry of 40+ AI models from 11 providers with short aliases, pricing data, and automatic API key detection.

What It Provides

Supported Providers

Short Aliases - Anthropic

Short Aliases - OpenAI

Browsing Models

# See complete catalog
/converge catalog

# Search by keyword
/converge search code
/converge search fast
/converge search free

# Show only models with API keys set
/converge available

Model Tiers

📁 Context Management

OCCode provides powerful tools for managing which files and information the AI can access.

Basic Context Commands

Persistent Context (Pinning)

Pin files to keep them in context across all sessions:

/pin src/config.ts
/pin README.md
/unpin src/config.ts

Exclusion Patterns

Exclude files or directories from being added to context:

/exclude node_modules
/exclude "*.test.ts"
/exclude "**/tests/**"
/include node_modules  # Remove exclusion

Context Overview

The /context command shows:

• Number of files in context
• Total token count
• Pinned files (permanent)
• Session files (temporary)
• Exclusion patterns

⌨️ Command Reference

Provider & Model

Model Profiles

Convergence

Context Management

Session Management

Git Integration

Checkpoints & Undo

Daemon & Indexing

Execution Mode

Help

🔧 Git Integration

Git Status

/git

Shows:

• Current branch
• Staged files
• Unstaged changes
• Untracked files
• Commit status

AI-Powered Commits

/commit

OCCode will:

1. Analyze git diff
2. Generate descriptive commit message
3. Show you the message for approval
4. Create the commit if approved

Enhanced Diff

/diff src/main.ts
/diff --side-by-side src/main.ts src/utils.ts
/diff --no-syntax src/**/*.ts

Features:

• Syntax highlighting
• Side-by-side comparison
• Context lines
• Line numbers

💰 Cost & Token Tracking

OCCode provides real-time cost tracking with model-specific pricing across 20+ pricing tiers.

View Costs

/status  # Quick overview
/cost    # Detailed breakdown

What's Tracked

• Input Tokens: Tokens sent to the model
• Output Tokens: Tokens generated by the model
• Cost Per Turn: Cost breakdown for each message
• Total Session Cost: Cumulative cost
• Model-Specific Pricing: Accurate rates for each model

Convergence Cost Tracking

When using convergence, costs are tracked for:

• Each participant model
• Aggregator model
• Total ensemble cost
• Per-model breakdown

💾 Checkpoints & Undo

Creating Checkpoints

Save a snapshot of all file states:

/checkpoint "Before refactoring auth module"
/checkpoint "Working state before experiment"

Managing Checkpoints

/checkpoint list              # List all checkpoints
/checkpoint restore cp_123    # Restore a specific checkpoint

Quick Undo

Undo the last file change with a single command:

/undo

What's Saved

Checkpoints include:

• All modified file contents
• Timestamp
• Your description message
• File paths

🤖 AI Providers

OCCode supports 11 AI providers with 40+ models.

Setting Up Providers

Via Environment Variables (Recommended)

# Anthropic (Claude)
export ANTHROPIC_API_KEY="sk-ant-..."

# OpenAI (GPT)
export OPENAI_API_KEY="sk-..."

# Google (Gemini)
export GOOGLE_API_KEY="..."

# DeepSeek
export DEEPSEEK_API_KEY="..."

# Mistral
export MISTRAL_API_KEY="..."

# Groq
export GROQ_API_KEY="..."

Via OCCode Commands

/provider anthropic
/api_key sk-ant-your-key-here

Switching Providers

/provider anthropic
/model sonnet

/provider openai
/model gpt4o

/provider google
/model gemini-pro

Custom Endpoints

For self-hosted or custom API endpoints:

/api_url https://your-custom-api.com/v1
/api_url reset  # Reset to default

Provider Features Comparison

⚙️ Configuration

Configuration Files

OCCode stores configuration in ~/.occode/:

• config.json - Global settings
• profiles.json - Model profiles
• convergence.json - Convergence configuration
• sessions/ - Session history
• checkpoints/ - File snapshots

Global Configuration

Edit ~/.occode/config.json:

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "apiEndpoint": null,
  "maxTokens": 4096,
  "temperature": 0.7,
  "autoApprove": false,
  "theme": "auto"
}

Profile Configuration

Profiles are stored in ~/.occode/profiles.json:

{
  "profiles": {
    "fast": {
      "name": "fast",
      "provider": "anthropic",
      "model": "claude-haiku-4-5-20251001",
      "temperature": 0.3,
      "maxTokens": 2048,
      "triggerPrefix": "quick:",
      "description": "Quick answers, low cost"
    }
  },
  "activeProfile": "fast",
  "defaultProfile": null
}

Environment Variable Priority

Configuration priority (highest to lowest):

1. Active model profile
2. Environment variables (OCCODE_*)
3. Global config file
4. Built-in defaults

🔍 Troubleshooting

API Key Issues

Problem: "No API key found"

Solution:

# Check if environment variable is set
echo $ANTHROPIC_API_KEY

# Set via OCCode
/api_key your-key-here

# Or set environment variable
export ANTHROPIC_API_KEY="your-key"

Problem: "Invalid API key"

Solution:

• Verify key format (should start with sk-ant- for Anthropic)
• Check if key is active in your provider dashboard
• Ensure no extra spaces or quotes in environment variable

Model Profile Issues

Problem: "Profile not found"

Solution:

# List all profiles to check spelling
/profile

# Recreate if needed
/profile template fast

Problem: "Prefix not triggering"

Solution:

• Check prefix is set: /profile (should show [quick:] next to profile)
• Ensure exact match with colon: quick: not quick
• Set prefix: /profile prefix fast quick:

Convergence Issues

Problem: "No models configured"

Solution:

# Use a preset
/converge preset duo-merge

# Or add models manually
/converge add sonnet
/converge add gpt4o
/converge aggregator sonnet

Problem: "High costs"

Solution:

# Use cost-effective strategy
/converge preset code-review

# Use cheaper models
/converge add haiku
/converge add mini
/converge aggregator haiku

# Disable when not needed
/converge off

Context Issues

Problem: "Too many tokens in context"

Solution:

# Remove large files
/context remove large-file.json

# Exclude test files
/exclude "*.test.ts"
/exclude "**/tests/**"

# Compact conversation history
/compact

General Issues

Problem: "Command not working"

Solution:

• Ensure command starts with /
• Check spelling: /help to see all commands
• Try /debug for more detailed error messages

Problem: "Session won't resume"

Solution:

# Check sessions directory
ls ~/.occode/sessions/

# Start fresh session
occode --new-session

Getting Help

• In-app Help: /help
• Debug Mode: /debug
• Support Email: support@opencan.ai
• Documentation: opencan.ai/docs
• Website: opencan.ai