CCAI - Claude Code AI Assistant

English | 中文

CCAI is an intelligent AI provider management and routing tool for Claude Code, designed to help you efficiently delegate tool-intensive tasks to cost-effective AI providers.

Features

🚀 Multi-Provider Management: Configure and manage multiple AI providers (GLM, MiniMax, etc.)
🧠 Intelligent Routing: Automatically select the best provider based on task characteristics
💰 Cost Optimization: Route tasks to cost-efficient providers for batch operations
📊 Performance Tracking: Log and analyze provider performance over time
🔄 Easy Updates: Seamlessly update provider configurations and routing strategies
🛠️ Type-Safe: Built with TypeScript for complete type safety

Installation

npm i -g ccai
ccai init

This will install CCAI templates to your ~/.claude directory.

Quick Start

1. Add a Provider

npx ccai add glm

This creates a configuration file at ~/.claude/ccai/settings-glm.json.

2. Configure Provider Settings

Edit the provider configuration:

npx ccai get glm

Update the configuration file with your provider's API key and settings:

{
  "ccai": {
    "name": "GLM",
    "description": "GLM-4.6 model, excellent for tool calling and batch processing",
    "systemPrompt": "## GLM Model\n\nYou are GLM-4.6, optimized for...",
    "disabled": false
  },
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your-api-key-here",
    "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/paas/v4/",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

3. Enable Provider

npx ccai enable glm

This generates the /ccai-glm command in Claude Code.

4. Use in Claude Code

Direct Execution:

/ccai-glm "Fetch documentation from 10 URLs and summarize key points"

Smart Routing:

/ccai "Process 100 CSV files and generate a summary report"

The smart router will analyze the task and select the most suitable provider.

Advanced Configuration

Custom Commands

CCAI supports custom command execution for non-Claude CLI providers (e.g., OpenAI API, GLM API). You can configure custom commands in your provider settings:

{
  "ccai": {
    "name": "OpenAI GPT-4",
    "command": {
      "executable": "curl",
      "args": [
        "-X",
        "POST",
        "https://api.openai.com/v1/chat/completions",
        "-H",
        "Content-Type: application/json",
        "-H",
        "Authorization: Bearer {{ENV.OPENAI_API_KEY}}",
        "-d",
        "{\"model\":\"gpt-4\",\"messages\":[{\"role\":\"system\",\"content\":\"{{SYSTEM_PROMPT}}\"},{\"role\":\"user\",\"content\":\"{{PROMPT}}\"}]}"
      ]
    }
  }
}

Supported Placeholders:

{{SETTINGS_PATH}} - Path to merged settings file
{{SYSTEM_PROMPT}} - Merged system prompt content
{{PROMPT}} - Full prompt with context (from --prompt, --prompt-file, or inputPrompt args)
{{INPUT}} - Input data that conforms to inputSchema (from --input, --input-file, or inputPrompt args)
{{TASK}} - Deprecated: Use {{PROMPT}} instead (kept for backward compatibility)
{{ENV.*}} - Environment variables (e.g., {{ENV.API_KEY}})

Variant Matching

CCAI supports conditional arguments using variant matching, allowing you to dynamically change command arguments based on runtime options:

{
  "ccai": {
    "command": {
      "executable": "claude",
      "args": [
        "--settings",
        "{{SETTINGS_PATH}}",
        "--output-format",
        {
          "{{log}}+{{prettyJson}}": {
            "true+true": ["stream-json", "--verbose"],
            "false+false": ["json"],
            "*": ["json"]
          }
        },
        {
          "{{sessionId}}": {
            "{undefined,null}": [],
            "*": ["--resume", "{{sessionId}}"]
          }
        },
        "-p",
        "{{PROMPT}}"
      ]
    }
  }
}

How it works:

Expression: First level key (e.g., "{{log}}+{{prettyJson}}") - placeholders are replaced with actual values
Pattern Matching: Second level keys use minimatch glob patterns:
- Exact match: "true"
- Wildcard: "*"
- Brace expansion: "{true,false}" or "{undefined,null}"
- Glob patterns: "true+*", "*+*+*"
Result: Matched pattern returns an array of arguments to insert

Available Placeholders for Variant Matching:

{{log}} - Boolean from --log option
{{prettyJson}} - Boolean from --pretty-json option
{{sessionId}} - String from --session-id option (or "undefined")
{{taskType}} - String from --example option (or "undefined")
Any custom placeholder from CommandPlaceholders

Multi-line Text Support

Both description and systemPrompt support string[] for better readability:

{
  "ccai": {
    "description": [
      "Provider description line 1",
      "",
      "**Strengths**:",
      "- Feature 1",
      "- Feature 2"
    ],
    "systemPrompt": [
      "## Instructions",
      "",
      "You are using this model.",
      "",
      "1. Guideline 1",
      "2. Guideline 2"
    ]
  }
}

Arrays are automatically joined with newlines (\n), making JSON configuration files much more readable than using \n escape sequences.

Input/Output Schemas

Define input and output schemas to guide AI behavior and validate responses:

{
  "ccai": {
    "inputSchema": {
      "type": "object",
      "properties": {
        "task": {
          "type": "string",
          "description": "The task to be executed"
        }
      },
      "required": ["task"]
    },
    "outputSchema": {
      "type": "object",
      "properties": {
        "result": {
          "type": "string",
          "description": "The execution result"
        },
        "status": {
          "type": "string",
          "enum": ["success", "error"]
        }
      },
      "required": ["result", "status"]
    }
  }
}

Schema Features:

Input Schema: Injected into system prompt to guide AI on expected input format
Output Schema: Injected into system prompt to guide AI on expected output format
Validation: Output is validated against schema; warnings are logged but execution continues
Documentation: Schemas are formatted as readable Markdown in the system prompt

Example Output:

See examples/openai-provider.json and examples/glm-provider.json for complete configuration examples.

CLI Commands

User Commands

npx ccai init - Initialize CCAI templates
npx ccai add <provider> - Add a new provider
npx ccai list - List all configured providers
npx ccai get <provider> - View provider configuration
npx ccai enable <provider> - Enable a provider
npx ccai disable <provider> - Disable a provider
npx ccai update - Update command files

Adding Providers with Command Templates

The add command supports a --command option that automatically configures providers with predefined command templates:

# Add Claude CLI provider (default behavior)
npx ccai add my-claude --command=claude

# Add Google Gemini CLI provider
npx ccai add my-gemini --command=gemini

# Add Anthropic Codex CLI provider
npx ccai add my-codex --command=codex

Template Features:

Each template includes:

Pre-configured command executable and arguments
Variant matching for dynamic behavior (logging, JSON formatting, session management)
Optimized system prompts for the specific CLI tool
Provider-specific descriptions

Claude Template:

Executable: claude
Features: Session management, logging, JSON formatting, task context injection
System Prompt: Emphasizes tool-calling, batch processing, and cost efficiency

Gemini Template:

Executable: gemini
Features: YOLO mode, JSON output, direct prompt execution
System Prompt: Highlights speed and reliability for simple tasks
Note: Currently does not support external session management

Codex Template:

Executable: codex
Features: Full auto mode, sandbox access, session resume capability
System Prompt: Optimized for autonomous execution and tool-intensive workflows

Example Configuration:

After running npx ccai add my-gemini --command=gemini, the generated configuration will include:

{
  "ccai": {
    "name": "Gemini",
    "description": [
      "Google Gemini CLI provider",
      "",
      "**Strengths**:",
      "- Fast response times",
      "- Good for simple tasks",
      "- JSON output support"
    ],
    "systemPrompt": [
      "You are executing tasks via Google Gemini CLI.",
      "Focus on providing fast, reliable responses."
    ],
    "command": {
      "executable": "gemini",
      "args": ["--yolo", "--output-format", "json", "--prompt", "{{PROMPT}}"]
    }
  }
}

You can then customize the configuration as needed using npx ccai get my-gemini.

Internal Commands (used by Claude Code)

npx ccai merge-settings <provider> - Merge provider settings
npx ccai merge-prompts --provider <name> - Merge system prompts
npx ccai run --provider <name> [prompt] - Execute tasks with specific provider

Run Command

The run command provides direct execution of tasks with AI providers, useful for testing and debugging.

Basic Usage

# Execute a task directly
npx ccai run --provider glm "analyze this code"

# Separate prompt and input
npx ccai run --provider glm --prompt "analyze the following" --input "code content"

# Read prompt from file
npx ccai run --provider glm --prompt-file ./prompt.txt

# Read input from file (uses inputSchema structure)
npx ccai run --provider glm --input-file ./data.json

# Combine: prompt from file, input from args
npx ccai run --provider glm --prompt-file ./context.md --input "specific data"

# Continue from previous session
npx ccai run --provider glm "continue" --session-id <uuid>

Prompt vs Input:

--prompt / --prompt-file: Full prompt with context (maps to {{PROMPT}} placeholder)
--input / --input-file: Input data conforming to inputSchema (maps to {{INPUT}} placeholder)
If neither is specified, the command arguments are used for both
If only one is specified, the other defaults to the same value

Print Command Mode

The --print-command option prints the final Claude command without executing it, useful for debugging or understanding the execution pipeline.

Output Formats:

bash (default on macOS/Linux) - Uses bash file substitution $(< "file")
ps (default on Windows) - Uses PowerShell syntax $(Get-Content "file" -Raw)
json - Outputs command as JSON array for programmatic use
text - Outputs raw escaped command string

Examples:

# Print command with OS-appropriate format
npx ccai run --provider glm "analyze code" --print-command

# macOS/Linux output:
# claude --settings /path/to/settings.json --system-prompt $(< "/tmp/prompt.md") -p 'analyze code'

# Force bash format
npx ccai run --provider glm "analyze code" --print-command=bash

# PowerShell format
npx ccai run --provider glm "analyze code" --print-command=ps

# JSON format (for scripts)
npx ccai run --provider glm "analyze code" --print-command=json
# ["claude","--settings","/path/to/settings.json","--system-prompt","..."]

# Print command structure without prompt
npx ccai run --provider glm --print-command
# (omits -p parameter when no prompt provided)

Advanced Options

# Task type hint for prompt optimization
npx ccai run --provider glm "scrape website" --example web-scraping

# Enable detailed logging
npx ccai run --provider glm "process data" --log

# Pretty JSON output
npx ccai run --provider glm "generate report" --pretty-json

# Custom output formatting
npx ccai run --provider glm "analyze" --format "{{role}}: {{content}}"

Options Reference

Option	Type	Description
`--provider`	string	Required. Provider name (e.g., glm, minimax)
`--example`	string	Task type hint (web-scraping, code-generation, data-processing, etc.)
`--session-id`	uuid	Continue from previous session
`--plan-only`	boolean	Generate execution plan only (for intelligent routing)
`--log`	boolean	Enable detailed logging with stream-json output
`--pretty-json`	boolean	Format JSON output in human-readable way
`--format`	string	Custom output template
`--prompt-file`	path	Read prompt from file
`--print-command`	string\|boolean	Print command without executing (bash\|ps\|json\|text)

Use Cases

1. Testing Provider Configuration:

npx ccai run --provider glm "test message" --print-command

2. Debugging Execution Issues:

npx ccai run --provider glm "task" --log --print-command=json

3. Generating Shell Scripts:

npx ccai run --provider glm "analysis task" --print-command > run.sh
chmod +x run.sh
./run.sh

4. CI/CD Integration:

# Generate command for CI pipeline
COMMAND=$(npx ccai run --provider glm "lint code" --print-command=json)
echo $COMMAND | jq -r 'join(" ")' | bash

Architecture

Directory Structure

~/.claude/
├── ccai/
│   ├── settings-glm.json          # GLM configuration
│   ├── settings-minimax.json      # MiniMax configuration
│   ├── routing.md                 # Routing strategy
│   └── log/                       # Task execution logs
├── commands/
│   ├── ccai.md                    # Smart routing command
│   ├── ccai-glm.md                # GLM direct command
│   ├── ccai-minimax.md            # MiniMax direct command
│   └── ccaieval.md                # Performance evaluation command
└── skills/
    └── ccai/
        ├── SKILL.md               # Delegation guidelines
        └── examples/              # Task-specific examples

Configuration Schema

interface ProviderSettings {
  ccai: {
    name?: string; // Display name
    description?: string; // Capabilities description
    systemPrompt?: string; // Provider-specific prompt
    disabled?: boolean; // Enable/disable status
  };
  env: {
    ANTHROPIC_AUTH_TOKEN: string;
    ANTHROPIC_BASE_URL: string;
    [key: string]: string;
  };
}

Routing Strategy

CCAI uses a Markdown-based routing strategy (~/.claude/ccai/routing.md) that describes:

Routing Principles: Cost, performance, and load balancing rules
Task Type Matching: Which providers excel at specific task types
Provider Capabilities: Detailed descriptions of each provider's strengths
Special Rules: Custom routing logic and constraints

Example routing rule:

### Web Scraping Tasks

- **Primary**: Provider with strong tool-calling capabilities
- **Max Cost**: $0.10
- **Evaluation**: Speed > Cost

Task Types

CCAI supports task-specific optimizations for:

🌐 web-scraping: Web data extraction and document fetching
💻 code-generation: Generating boilerplate and components
📊 data-processing: Batch data transformation and analysis
🔍 code-analysis: Codebase search and pattern detection
📚 documentation-research: Technical documentation research
🎨 visual-inspection: UI testing and screenshot analysis

Performance Evaluation

Analyze provider performance and update routing strategy:

/ccaieval

This command:

Collects task logs from the past 7 days
Calculates success rates, costs, and performance metrics
Generates recommendations
Updates routing.md with insights

Development

Prerequisites

Node.js 18+
pnpm 10+

Build from Source

# Clone repository
git clone https://github.com/Gaubee/ccai.git
cd ccai

# Install dependencies
pnpm install

# Build
pnpm build

# Test
pnpm dev

Project Structure

ccai/
├── src/
│   ├── cli/              # CLI implementation
│   ├── core/             # Core modules
│   ├── types/            # Type definitions
│   ├── utils/            # Utilities
│   └── generated/        # Generated template files
├── scripts/
│   └── generate-templates.ts  # Template generator
├── templates/            # Template files
│   ├── commands/         # Command templates
│   ├── skills/           # Skill templates
│   └── ccai/             # Configuration templates
└── dist/                 # Built output

Design Principles

CCAI follows these core principles:

KISS (Keep It Simple): Clean CLI interface and clear functionality
YAGNI (You Aren't Gonna Need It): Implement only essential features
DRY (Don't Repeat Yourself): Shared skills and reusable components
SOLID: Single responsibility, extensible design, proper abstractions

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE for details.

Name		Name	Last commit message	Last commit date
Latest commit History 39 Commits
examples		examples
references		references
scripts		scripts
src		src
templates		templates
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
CHAT.md		CHAT.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README-zh.md		README-zh.md
README.md		README.md
SPEC.md		SPEC.md
oxlint.json		oxlint.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
rolldown.config.ts		rolldown.config.ts
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

License

jixoai/ccai

Folders and files

Latest commit

History

Repository files navigation

CCAI - Claude Code AI Assistant

Features

Installation

Quick Start

1. Add a Provider

2. Configure Provider Settings

3. Enable Provider

4. Use in Claude Code

Advanced Configuration

Custom Commands

Variant Matching

Multi-line Text Support

Input/Output Schemas

CLI Commands

User Commands

Adding Providers with Command Templates

Internal Commands (used by Claude Code)

Run Command

Basic Usage

Print Command Mode

Advanced Options

Options Reference

Use Cases

Architecture

Directory Structure

Configuration Schema

Routing Strategy

Task Types

Performance Evaluation

Development

Prerequisites

Build from Source

Project Structure

Design Principles

Contributing

License

Links

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

Packages