README.md

Your AI coding wingman for the terminal

Website • Features • Installation • Quick Start • Commands • Tools • Extend

Highlights

Features

Installation

Via npm (Recommended)

npm install -g codi-cli

From Source

Requirements:

• Node.js >=22 <23
• pnpm (via Corepack)

# Clone the repository
git clone https://github.com/laynepenney/codi.git
cd codi

# Install dependencies
corepack enable
pnpm install

# Build the project
pnpm run build

# Optional: Link globally
pnpm link --global

Platform Notes

brew install ollama
ollama serve  # In a separate terminal
ollama pull llama3.2

# Using nvm
nvm install 22
nvm use 22

Quick Start

With Claude API (Anthropic)

export ANTHROPIC_API_KEY="your-key-here"
codi

Get your API key: console.anthropic.com

Available models: claude-sonnet-4-20250514 (default), claude-3-5-haiku-latest, claude-opus-4-20250514

With OpenAI API

export OPENAI_API_KEY="your-key-here"
codi --provider openai

Get your API key: platform.openai.com/api-keys

Available models: gpt-4o (default), gpt-4o-mini, o1-preview, o1-mini

With Ollama (Local/Free)

# 1. Install Ollama from https://ollama.ai
# 2. Start the server (runs on localhost:11434)
ollama serve

# 3. Pull a model (in another terminal)
ollama pull llama3.2

# 4. Run Codi
codi --provider ollama --model llama3.2

Recommended models: llama3.2 (fast), deepseek-coder (code), qwen2.5-coder (code)

With Ollama Cloud (Hosted)

# Sign in to Ollama Cloud (one-time setup)
ollama signin

# Or use an API key from https://ollama.com/settings/keys
export OLLAMA_API_KEY="your-api-key"

# Run with cloud models
codi --provider ollama-cloud --model llama3.2

Get your API key: ollama.com/settings/keys

With RunPod Serverless

export RUNPOD_API_KEY="your-key-here"
codi --provider runpod --endpoint-id your-endpoint-id

Get your API key: runpod.io/console/user/settings

CLI Options

Child Mode (Multi-Agent)

These options are used internally when spawning worker agents:

Keyboard Shortcuts

Codi supports several keyboard shortcuts for efficient interaction:

ESI Interrupt Feature: Press ESC at any time during AI processing to cancel and return to the prompt. This is useful for:

• Long-running tool calls (e.g., test suites)
• Mistaken commands with large operations
• Infinite loops or stuck operations
• Quick iterations without waiting for completion

Commands

# Spawn workers for parallel tasks
/delegate feat/auth "implement OAuth2 login"
/delegate feat/api "add REST endpoints for users"

# Monitor progress
/workers

# Workers route permission requests to you for approval
# [feat/auth] Permission: write_file → approve/deny?

Tools

The AI has access to these tools for interacting with your codebase:

Symbol Index Tools

The AI can use these tools for IDE-like code navigation:

Note: Run /symbols rebuild to build the index before using symbol tools.

Safety Features

Dangerous operations trigger confirmation prompts:

• Destructive bash commands (rm -rf, sudo, etc.)
• Force git operations (--force)
• System modifications (chmod 777, disk operations)
• Remote script execution (piped curl/wget)

Diff Preview: See exactly what will change before approving file modifications.

Undo System: Use /revert-file to undo any file change.

Project Detection

Codi automatically detects your project type and adapts its responses:

Workspace Configuration

Create a .codi.json in your project root (or use /init --config):

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "baseUrl": "https://api.example.com",
  "autoApprove": ["read_file", "glob", "grep", "list_directory"],
  "approvedCategories": ["read-only", "navigation"],
  "dangerousPatterns": ["custom-pattern-.*"],
  "systemPromptAdditions": "Always use TypeScript strict mode.",
  "projectContext": "This is a React app using Next.js 14.",
  "commandAliases": {
    "t": "/test src/",
    "b": "/build"
  },
  "defaultSession": "my-project",
  "enableCompression": false,
  "maxContextTokens": 100000,
  "models": {
    "summarize": {
      "provider": "ollama",
      "model": "llama3.2"
    }
  },
  "rag": {
    "enabled": true,
    "excludePatterns": ["**/node_modules/**", "**/.git/**"],
    "maxChunkSize": 1000,
    "maxResults": 5
  },
  "tools": {
    "disabled": ["web_search"],
    "defaults": {
      "bash": { "timeout": 30000 }
    }
  }
}

Configuration Options

Model Map (Multi-Model Orchestration)

Create codi-models.yaml for Docker-compose style multi-model workflows:

version: "1"

models:
  haiku:
    provider: anthropic
    model: claude-3-5-haiku-latest
  sonnet:
    provider: anthropic
    model: claude-sonnet-4-20250514
  local:
    provider: ollama
    model: llama3.2

tasks:
  fast: { model: haiku }
  code: { model: sonnet }
  complex: { model: sonnet }

model-roles:
  fast:
    anthropic: haiku
    openai: gpt-5-nano
    ollama: local
  capable:
    anthropic: sonnet
    openai: gpt-5
    ollama: local

pipelines:
  code-review:
    description: "Multi-step code review"
    steps:
      - name: scan
        role: fast
        prompt: "Quick scan: {input}"
        output: issues
      - name: analyze
        role: capable
        prompt: "Deep analysis: {issues}"
        output: analysis
    result: "{analysis}"

# Execute pipeline with different providers
/pipeline code-review src/agent.ts
/pipeline --provider anthropic code-review src/agent.ts

Extending Codi

Adding a Tool

// src/tools/my-tool.ts
import { BaseTool } from './base.js';

export class MyTool extends BaseTool {
  getDefinition() {
    return {
      name: 'my_tool',
      description: 'Description for the AI',
      input_schema: {
        type: 'object',
        properties: {
          param: { type: 'string', description: 'Parameter' }
        },
        required: ['param']
      }
    };
  }

  async execute(input: Record<string, unknown>) {
    return 'Result';
  }
}

Adding a Command

// src/commands/my-commands.ts
import { registerCommand } from './index.js';

export const myCommand = {
  name: 'mycommand',
  aliases: ['mc'],
  description: 'Description shown in /help',
  usage: '/mycommand <arg>',
  execute: async (args) => `Perform task with: ${args}`,
};

registerCommand(myCommand);

Plugins (Coming Soon)

Plugin support is temporarily disabled while we improve the architecture. The plugin system will allow custom commands, tools, and providers via ~/.codi/plugins/.

Development

pnpm dev          # Run with TypeScript
pnpm test         # Run tests
pnpm test:watch   # Watch mode
pnpm build        # Build for production

PTY Integration Tests

CODI_RUN_PTY_TESTS=1 pnpm test

Architecture

codi/
├── src/
│   ├── index.ts           # CLI entry point & REPL
│   ├── agent.ts           # Agent loop orchestration
│   ├── context.ts         # Project detection
│   ├── commands/          # Slash command system
│   ├── providers/         # AI model backends
│   ├── tools/             # Filesystem interaction
│   ├── rag/               # Semantic code search
│   ├── model-map/         # Multi-model orchestration
│   ├── orchestrate/       # Multi-agent orchestration (IPC, worktrees)
│   └── symbol-index/      # Code symbol indexing
├── tests/                 # Vitest test suite
├── docs/                  # Documentation
└── assets/                # Branding assets

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (pnpm test)
5. Commit (git commit -m 'Add amazing feature')
6. Push (git push origin feature/amazing-feature)
7. Open a Pull Request

See CODI.md for detailed contribution guidelines.

🗺️ Roadmap

✅ Completed Features

• Multi-provider support (Claude, OpenAI, Ollama)
• Comprehensive tool suite (28+ file, git, code tools)
• Git integration (/commit, /pr, /branch commands)
• Session persistence with conversation history
• Session debugging with breakpoints and checkpoints
• Multi-agent orchestration with IPC communication
• Cost/usage tracking with historical analytics
• RAG system for semantic code search
• Web search via DuckDuckGo
• Model map for multi-model workflows

🔲 Planned Features

• Enhanced MCP support: Better tool interoperability
• Visual debugging: GUI for session debugging
• Team features: Collaborative sessions

License

AGPL-3.0-or-later (see LICENSE)

Commercial licenses available for proprietary use. See LICENSING.md for details.

Built with 💜 by developers, for developers