aicodeswitch 1.0.0 → 1.1.1

package/CLAUDE.md

@@ -0,0 +1,182 @@
+```
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+```
+
+## AI Code Switch - Project Overview
+
+AI Code Switch is a local proxy server that manages AI programming tool connections to large language models, allowing tools like Claude Code and Codex to use custom model APIs instead of official ones.
+
+## Development Commands
+
+### Installation
+```bash
+npm install
+```
+
+### Development
+```bash
+npm run dev              # Run both UI and server in watch mode
+npm run dev:ui           # Run only React UI (Vite dev server)
+npm run dev:server       # Run only Node.js server (TSX watch)
+```
+
+### Build
+```bash
+npm run build            # Build both UI and server
+npm run build:ui         # Build React UI to dist/ui
+npm run build:server     # Build TypeScript server to dist/server
+```
+
+### Linting
+```bash
+npm run lint             # Run ESLint on all .ts/.tsx files
+```
+
+### CLI Commands
+```bash
+npm link                 # Link local package for CLI testing
+aicos start              # Start the proxy server
+aicos stop               # Stop the proxy server
+aicos restart            # Restart the proxy server
+```
+
+## Architecture
+
+### High-Level Structure
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     AI Code Switch                          │
+├─────────────────────────────────────────────────────────────┤
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
+│  │   React UI   │  │  Express API │  │  Proxy Core  │     │
+│  │  (Vite dev)  │  │  (Node.js)   │  │              │     │
+│  └──────────────┘  └──────────────┘  └──────────────┘     │
+│            │              │              │                  │
+│            └──────────────┼──────────────┘                  │
+│                           ▼                                 │
+│                    ┌──────────────┐                        │
+│                    │   Database   │                        │
+│                    │  (SQLite3)   │                        │
+│                    └──────────────┘                        │
+│                           │                                 │
+│                           ▼                                 │
+│                    ┌──────────────┐                        │
+│                    │  Transformers │                        │
+│                    │  (Stream/SSE) │                        │
+│                    └──────────────┘                        │
+│                           │                                 │
+│                           ▼                                 │
+│                    ┌──────────────┐                        │
+│                    │  Upstream    │                        │
+│                    │  APIs (LLMs) │                        │
+│                    └──────────────┘                        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Core Components
+
+#### 1. Server (Node.js/Express) - `server/main.ts`
+- Main entry point
+- Configures Express with CORS, body parsing
+- Reads configuration from `~/.aicodeswitch/aicodeswitch.conf`
+- Sets up authentication middleware
+- Registers all API routes
+- Initializes database and proxy server
+
+#### 2. Proxy Server - `server/proxy-server.ts`
+- **Route Matching**: Finds active route based on target type (claude-code/codex)
+- **Rule Matching**: Determines content type from request (image-understanding/thinking/long-context/background/default)
+- **Request Transformation**: Converts between different API formats (Claude ↔ OpenAI ↔ OpenAI Responses)
+- **Streaming**: Handles SSE (Server-Sent Events) streaming responses with real-time transformation
+- **Logging**: Tracks requests, responses, and errors
+
+#### 3. Transformers - `server/transformers/`
+- **streaming.ts**: SSE parsing/serialization and event transformation
+- **claude-openai.ts**: Claude ↔ OpenAI Chat format conversion
+- **openai-responses.ts**: OpenAI Responses format conversion
+- **chunk-collector.ts**: Collects streaming chunks for logging
+
+#### 4. Database - `server/database.ts`
+- SQLite3 database wrapper
+- Manages: Vendors, API Services, Routes, Rules, Logs
+- Configuration storage (API key, logging settings, etc.)
+
+#### 5. UI (React) - `ui/`
+- Main app: `App.tsx` - Navigation and layout
+- Pages:
+  - `VendorsPage.tsx` - Manage AI service vendors
+  - `RoutesPage.tsx` - Configure routing rules
+  - `LogsPage.tsx` - View request/access/error logs
+  - `SettingsPage.tsx` - Application settings
+  - `WriteConfigPage.tsx` - Overwrite Claude Code/Codex config files
+  - `UsagePage.tsx` - Usage statistics
+
+#### 6. Types - `types/`
+- TypeScript type definitions for:
+  - Database models (Vendors, Services, Routes, Rules)
+  - API requests/responses
+  - Configuration
+  - Token usage tracking
+
+#### 7. CLI - `bin/`
+- `cli.js` - Main CLI entry point
+- `start.js` - Server startup with PID management
+- `stop.js` - Server shutdown
+- `restart.js` - Restart server
+
+## Key Features
+
+### Routing System
+- **Routes**: Define target type (Claude Code or Codex) and activation status
+- **Rules**: Match requests by content type and route to specific API services
+- **Content Type Detection**:
+  - `image-understanding`: Requests with image content
+  - `thinking`: Requests with reasoning/thinking signals
+  - `long-context`: Requests with large context (≥12000 chars or ≥8000 max tokens)
+  - `background`: Background/priority requests
+  - `default`: All other requests
+
+### Request Transformation
+- Supports multiple source types:
+  - OpenAI Chat
+  - OpenAI Code
+  - OpenAI Responses
+  - Claude Chat
+  - Claude Code
+  - DeepSeek Chat
+
+### Configuration Management
+- Writes/ restores Claude Code config files (`~/.claude/settings.json`, `~/.claude.json`)
+- Writes/ restores Codex config files (`~/.codex/config.toml`, `~/.codex/auth.json`)
+- Exports/ imports encrypted configuration data
+
+### Logging
+- Request logs: Detailed API call records with token usage
+- Access logs: System access records
+- Error logs: Error and exception records
+
+## Development Tips
+
+1. **Environment Variables**: Copy `.env.example` to `.env` and modify as needed
+2. **Data Directory**: Default: `~/.aicodeswitch/data/` (SQLite3 database)
+3. **Config File**: `~/.aicodeswitch/aicodeswitch.conf` (HOST, PORT, AUTH)
+4. **Dev Ports**: UI (4568), Server (4567) - configured in `vite.config.ts` and `server/main.ts`
+5. **API Endpoints**: All routes are prefixed with `/api/` except proxy routes (`/claude-code/`, `/codex/`)
+
+## Build and Deployment
+
+1. Run `npm run build` to create production builds
+2. UI build outputs to `dist/ui/` (static files)
+3. Server build outputs to `dist/server/` (JavaScript)
+4. Configuration files are created in user's home directory on first run
+
+## Technology Stack
+
+- **Backend**: Node.js, Express, TypeScript, SQLite3
+- **Frontend**: React 18, TypeScript, Vite, React Router
+- **Streaming**: SSE (Server-Sent Events)
+- **HTTP Client**: Axios
+- **Encryption**: CryptoJS (AES)
+- **CLI**: Yargs-like custom implementation