cc-x10ded 3.0.16 → 3.0.18

package/PLUGINS.md

@@ -0,0 +1,173 @@
+# ccx Plugin System
+
+Extend ccx with custom model providers.
+
+## Overview
+
+The plugin system allows you to add any OpenAI-compatible API as a provider in ccx. Plugins are discovered from `~/.config/claude-glm/plugins/` and automatically loaded at runtime.
+
+## Quick Start
+
+### 1. Create Plugin Directory
+
+```bash
+mkdir -p ~/.config/claude-glm/plugins/my-provider
+```
+
+### 2. Create Plugin Manifest
+
+Create `plugin.json` in your plugin directory:
+
+```json
+{
+  "id": "my-provider",
+  "name": "My Custom Provider",
+  "version": "1.0.0",
+  "description": "A custom model provider",
+  "entry": "./dist/index.js"
+}
+```
+
+### 3. Write Plugin Implementation
+
+Create `index.ts` with your plugin code (see Example below).
+
+### 4. Build Plugin
+
+```bash
+bun build ./index.ts --outdir ./dist --target bun
+```
+
+### 5. Verify Installation
+
+```bash
+ccx models
+```
+
+Your provider should now appear in the list.
+
+## Plugin API
+
+### ProviderPlugin Interface
+
+```typescript
+import type { ProviderPlugin } from "@ccx/plugin-types";
+
+export default {
+  id: "my-provider",
+  name: "My Provider",
+  version: "1.0.0",
+  description: "Description of your provider",
+  models: [
+    { id: "model-1", name: "Model 1", contextWindow: 128000 },
+    { id: "model-2", name: "Model 2", contextWindow: 64000, default: true }
+  ],
+  createClient(config) {
+    return new MyProviderClient(config);
+  }
+} satisfies ProviderPlugin;
+```
+
+### ProviderClient Interface
+
+Your client must implement:
+
+```typescript
+interface ProviderClient {
+  readonly provider: string;
+
+  // Stream completions (required)
+  streamComplete(request: AnthropicRequest): AsyncGenerator<SSEMessage>;
+
+  // Get model info (optional)
+  getModelInfo(): ModelInfo | undefined;
+
+  // Health check (optional)
+  healthCheck(): Promise<HealthStatus>;
+}
+```
+
+### SSE Message Format
+
+Messages must be in Anthropic's SSE format:
+
+```typescript
+interface SSEMessage {
+  type: string;  // "message_start", "content_block_delta", "message_delta", "message_stop"
+  data: {
+    type?: string;
+    index?: number;
+    delta?: { type: "text_delta"; text: string };
+    stop_reason?: string;
+    usage?: { input_tokens: number; output_tokens: number };
+  };
+}
+```
+
+## Example: Ollama Plugin
+
+See `examples/plugins/ollama/` for a complete working example.
+
+## Type Definitions
+
+Install the official type definitions:
+
+```bash
+bun add -D @ccx/plugin-types
+```
+
+## Configuration
+
+Plugins can read configuration from the main config file:
+
+```json
+{
+  "plugins": {
+    "my-provider": {
+      "apiKey": "your-api-key",
+      "baseUrl": "https://api.example.com/v1",
+      "extra": {
+        "customOption": true
+      }
+    }
+  }
+}
+```
+
+## Best Practices
+
+1. **Handle errors gracefully** - Return meaningful error messages
+2. **Implement health checks** - Helps with `ccx doctor` diagnostics
+3. **Support streaming** - Users expect real-time responses
+4. **Respect rate limits** - Implement backoff on 429 errors
+5. **Use environment variables** - Allow API key via env vars
+
+## Publishing
+
+Want to share your plugin?
+
+1. Create a GitHub repository with your plugin code
+2. Add installation instructions to your README
+3. Submit a PR to add your plugin to the examples directory
+
+## Troubleshooting
+
+### Plugin Not Loading
+
+Check `ccx doctor` for plugin errors. Common issues:
+- Missing `plugin.json`
+- Entry file not found
+- TypeScript compilation errors
+
+### Model Not Found
+
+Ensure your model's `id` matches what users will type:
+- `ccx --model=my-provider:model-1`
+
+### API Errors
+
+Implement proper error handling in your plugin to surface meaningful errors to users.
+
+## API Reference
+
+See [@ccx/plugin-types](https://www.npmjs.com/package/@ccx/plugin-types) for complete type definitions.

package/examples/plugins/ollama/README.md

@@ -0,0 +1,67 @@
+# Ollama Plugin for ccx
+
+This example plugin demonstrates how to integrate local Ollama models with ccx.
+
+## Installation
+
+```bash
+# 1. Ensure Ollama is running (default: http://localhost:11434)
+ollama serve
+
+# 2. Pull a model
+ollama pull llama3.1
+
+# 3. Create plugin directory
+mkdir -p ~/.config/claude-glm/plugins/ollama
+
+# 4. Copy plugin files
+cp plugin.json ~/.config/claude-glm/plugins/ollama/
+cp dist/index.js ~/.config/claude-glm/plugins/ollama/
+
+# 5. Verify installation
+ccx models
+```
+
+## Building
+
+```bash
+# From the examples/plugins/ollama directory:
+bun build ./index.ts --outdir ./dist --target bun
+```
+
+## Configuration
+
+No API key required for local Ollama. The plugin connects to `http://localhost:11434` by default.
+
+You can override the base URL by adding to your config:
+
+```json
+{
+  "plugins": {
+    "ollama": {
+      "baseUrl": "http://ollama:11434"
+    }
+  }
+}
+```
+
+## Supported Models
+
+- Llama 3.1 8B (131K context)
+- Qwen 2.5 72B (131K context)
+- Mistral 7B (32K context)
+- CodeLlama 7B (16K context)
+- DeepSeek Coder 6.7B (16K context)
+
+## Adding Custom Models
+
+Edit `index.ts` to add more models:
+
+```typescript
+const MODELS: ModelInfo[] = [
+  { id: "your-model", name: "Your Model Name", contextWindow: 32768 },
+  // Add more models...
+];
+```
+
+Then rebuild and reinstall.

package/examples/plugins/ollama/index.ts

@@ -0,0 +1,138 @@
+import type {
+  ProviderPlugin,
+  ProviderClient,
+  PluginConfig,
+  ModelInfo,
+  HealthStatus,
+  SSEMessage,
+  AnthropicRequest
+} from "../../../packages/plugin-types/index";
+
+const MODELS: ModelInfo[] = [
+  { id: "llama3.1", name: "Llama 3.1 8B", contextWindow: 131072 },
+  { id: "qwen2.5", name: "Qwen 2.5 72B", contextWindow: 131072 },
+  { id: "mistral", name: "Mistral 7B", contextWindow: 32768 },
+  { id: "codellama", name: "CodeLlama 7B", contextWindow: 16384 },
+  { id: "deepseek-coder", name: "DeepSeek Coder 6.7B", contextWindow: 16384 }
+];
+
+export default {
+  id: "ollama",
+  name: "Ollama (Local)",
+  version: "1.0.0",
+  description: "Run local Ollama models with Claude Code",
+  models: MODELS,
+
+  createClient(config: PluginConfig): ProviderClient {
+    return new OllamaClient(config);
+  }
+} satisfies ProviderPlugin;
+
+class OllamaClient implements ProviderClient {
+  readonly provider = "ollama";
+  private baseUrl: string;
+
+  constructor(config: PluginConfig) {
+    this.baseUrl = config.baseUrl || "http://localhost:11434";
+  }
+
+  async *streamComplete(request: AnthropicRequest): AsyncGenerator<SSEMessage> {
+    const prompt = this.buildPrompt(request);
+
+    const response = await fetch(`${this.baseUrl}/api/generate`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        model: request.model,
+        prompt,
+        stream: true,
+        options: {
+          temperature: request.temperature ?? 0.7,
+          num_predict: request.max_tokens
+        }
+      })
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`Ollama error: ${response.status} ${errorText}`);
+    }
+
+    const reader = response.body?.getReader();
+    if (!reader) throw new Error("No response body from Ollama");
+
+    const decoder = new TextDecoder();
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      const chunk = decoder.decode(value);
+      const lines = chunk.split("\n");
+
+      for (const line of lines) {
+        if (!line.trim()) continue;
+
+        try {
+          const data = JSON.parse(line);
+
+          if (data.response) {
+            yield {
+              type: "content_block_delta",
+              data: { text: data.response }
+            };
+          }
+
+          if (data.done) {
+            yield {
+              type: "message_delta",
+              data: { stop_reason: "end_turn" }
+            };
+            yield {
+              type: "message_stop",
+              data: {}
+            };
+            break;
+          }
+        } catch {
+          continue;
+        }
+      }
+    }
+  }
+
+  getModelInfo(): ModelInfo | undefined {
+    return MODELS.find(m => m.id === "llama3.1");
+  }
+
+  async healthCheck(): Promise<HealthStatus> {
+    try {
+      const start = Date.now();
+      const response = await fetch(`${this.baseUrl}/api/tags`);
+      if (!response.ok) {
+        return { healthy: false, error: `HTTP ${response.status}` };
+      }
+      return { healthy: true, latencyMs: Date.now() - start };
+    } catch (error) {
+      return { healthy: false, error: (error as Error).message };
+    }
+  }
+
+  private buildPrompt(request: AnthropicRequest): string {
+    const parts: string[] = [];
+
+    if (request.system) {
+      parts.push(`<system>${request.system}</system>`);
+    }
+
+    for (const message of request.messages) {
+      const role = message.role === "assistant" ? "assistant" : "user";
+      const content = typeof message.content === "string"
+        ? message.content
+        : message.content.map(c => c.type === "text" ? c.text : "").join("");
+      parts.push(`<${role}>${content}</${role}>`);
+    }
+
+    return parts.join("\n");
+  }
+}

package/examples/plugins/ollama/plugin.json

@@ -0,0 +1,7 @@
+{
+  "id": "ollama",
+  "name": "Ollama (Local)",
+  "version": "1.0.0",
+  "description": "Use local Ollama models with Claude Code",
+  "entry": "./dist/index.js"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-x10ded",
-  "version": "3.0.16",
+  "version": "3.0.18",
   "description": "Extend Claude Code with custom OpenAI-compatible model providers",
   "repository": {
     "type": "git",

package/packages/plugin-types/index.ts

@@ -0,0 +1,60 @@
+export interface ProviderPlugin {
+  readonly id: string;
+  readonly name: string;
+  readonly version: string;
+  readonly description?: string;
+  readonly models: ModelInfo[];
+
+  createClient(config: PluginConfig): ProviderClient;
+}
+
+export interface ModelInfo {
+  readonly id: string;
+  readonly name: string;
+  readonly contextWindow?: number;
+  readonly maxOutputTokens?: number;
+  readonly capabilities?: readonly ("text" | "vision" | "tools")[];
+  readonly default?: boolean;
+}
+
+export interface ProviderClient {
+  readonly provider: string;
+
+  streamComplete(request: AnthropicRequest): AsyncGenerator<SSEMessage>;
+
+  getModelInfo(): ModelInfo | undefined;
+
+  healthCheck(): Promise<HealthStatus>;
+}
+
+export interface PluginConfig {
+  readonly apiKey?: string;
+  readonly baseUrl: string;
+  readonly extra?: Record<string, unknown>;
+}
+
+export interface HealthStatus {
+  readonly healthy: boolean;
+  readonly latencyMs?: number;
+  readonly error?: string;
+}
+
+export interface SSEMessage {
+  type: string;
+  data: unknown;
+}
+
+export interface AnthropicRequest {
+  model: string;
+  messages: AnthropicMessage[];
+  max_tokens: number;
+  temperature?: number;
+  system?: string;
+  tools?: unknown[];
+  stream?: boolean;
+}
+
+export interface AnthropicMessage {
+  role: "user" | "assistant" | "system";
+  content: string | Array<{ type: "text"; text: string } | { type: "tool_result"; content: string | unknown }>;
+}

package/packages/plugin-types/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@ccx/plugin-types",
+  "version": "1.0.0",
+  "description": "TypeScript types for ccx plugins",
+  "main": "index.ts",
+  "types": "index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "keywords": ["ccx", "claude", "plugin", "types"],
+  "author": "",
+  "license": "MIT"
+}