269 lines
9.2 KiB
Markdown
269 lines
9.2 KiB
Markdown
# Claudish Codebase Exploration - Findings Summary
|
|
|
|
## Executive Summary
|
|
|
|
Successfully explored the Claudish tool codebase at `mcp/claudish/`. The tool is a well-structured TypeScript/Bun CLI that proxies Claude Code requests to OpenRouter models via a local Anthropic API-compatible server.
|
|
|
|
**Key Finding:** Claudish already has an environment variable system for model communication, but does NOT currently support `ANTHROPIC_MODEL` or `ANTHROPIC_SMALL_FAST_MODEL`.
|
|
|
|
## What I Found
|
|
|
|
### 1. Current Model Communication System
|
|
|
|
Claudish uses a multi-layer approach to communicate model information:
|
|
|
|
**Layer 1: Environment Variables**
|
|
- `CLAUDISH_ACTIVE_MODEL_NAME` - Set by claudish, read by status line script
|
|
- Passed to Claude Code via environment at line 126 in `claude-runner.ts`
|
|
|
|
**Layer 2: Temporary Settings File**
|
|
- Path: `/tmp/claudish-settings-{timestamp}.json`
|
|
- Contains: Custom status line command
|
|
- Created dynamically to avoid modifying global Claude Code settings
|
|
|
|
**Layer 3: Token File**
|
|
- Path: `/tmp/claudish-tokens-{PORT}.json`
|
|
- Written by proxy server (line 816 in `proxy-server.ts`)
|
|
- Contains: cumulative input/output token counts
|
|
- Read by status line bash script for real-time context tracking
|
|
|
|
### 2. Architecture Overview
|
|
|
|
```
|
|
User CLI Input → parseArgs() → Config Object → createProxyServer() + runClaudeWithProxy()
|
|
↓
|
|
Environment Variables + Temp Settings File
|
|
↓
|
|
Claude Code Process Spawned
|
|
↓
|
|
Status Line reads CLAUDISH_ACTIVE_MODEL_NAME
|
|
```
|
|
|
|
### 3. Key Files & Their Purposes
|
|
|
|
| File | Location | Purpose | Size |
|
|
|------|----------|---------|------|
|
|
| `config.ts` | src/ | Environment variable names & model metadata | Small |
|
|
| `cli.ts` | src/ | Argument & env var parsing | Medium |
|
|
| `claude-runner.ts` | src/ | Claude execution & environment setup | Medium |
|
|
| `proxy-server.ts` | src/ | Hono-based proxy to OpenRouter | 58KB! |
|
|
| `types.ts` | src/ | TypeScript interfaces | Small |
|
|
|
|
### 4. Environment Variables Currently Supported
|
|
|
|
**User-Configurable:**
|
|
- `OPENROUTER_API_KEY` - Required for OpenRouter authentication
|
|
- `CLAUDISH_MODEL` - Default model selection
|
|
- `CLAUDISH_PORT` - Default proxy port
|
|
- `ANTHROPIC_API_KEY` - Placeholder to prevent Claude Code dialog
|
|
|
|
**Set by Claudish (read-only):**
|
|
- `CLAUDISH_ACTIVE_MODEL_NAME` - Model ID (set in claude-runner.ts:126)
|
|
- `ANTHROPIC_BASE_URL` - Proxy URL (set in claude-runner.ts:124)
|
|
|
|
### 5. Model Information Flow
|
|
|
|
**How the model gets to Claude Code UI:**
|
|
|
|
1. User specifies model via `--model` flag, `CLAUDISH_MODEL` env var, or interactive selection
|
|
2. Model ID stored in `config.model` (e.g., "x-ai/grok-code-fast-1")
|
|
3. Passed to `createProxyServer(port, apiKey, config.model, ...)` - line 81-87 in `index.ts`
|
|
4. Set as environment variable: `CLAUDISH_ACTIVE_MODEL_NAME` = model ID
|
|
5. Claude Code spawned with env vars (line 157 in `claude-runner.ts`)
|
|
6. Status line bash script reads `$CLAUDISH_ACTIVE_MODEL_NAME` and displays it
|
|
|
|
**Result:** Model name appears in status line as: `[dir] • x-ai/grok-code-fast-1 • $0.123 • 85%`
|
|
|
|
### 6. Token Information Flow
|
|
|
|
**How tokens are tracked for context display:**
|
|
|
|
1. Proxy server accumulates tokens during conversation
|
|
2. After each message, writes to `/tmp/claudish-tokens-{PORT}.json`:
|
|
```json
|
|
{
|
|
"input_tokens": 1234,
|
|
"output_tokens": 567,
|
|
"total_tokens": 1801,
|
|
"updated_at": 1731619200000
|
|
}
|
|
```
|
|
3. Status line bash script reads this file (line 55 in `claude-runner.ts`)
|
|
4. Calculates: `(maxTokens - usedTokens) * 100 / maxTokens = contextPercent`
|
|
5. Context window sizes defined in `MODEL_CONTEXT` object (lines 32-39)
|
|
|
|
### 7. Missing Environment Variable Support
|
|
|
|
**NOT IMPLEMENTED:**
|
|
- `ANTHROPIC_MODEL` - Could override model selection
|
|
- `ANTHROPIC_SMALL_FAST_MODEL` - Could specify fast model for internal tasks
|
|
- Custom display names for models
|
|
|
|
**Currently, if you set these variables, Claudish ignores them:**
|
|
```bash
|
|
export ANTHROPIC_MODEL=openai/gpt-5-codex # This does nothing
|
|
export ANTHROPIC_SMALL_FAST_MODEL=x-ai/grok-code-fast-1 # Also ignored
|
|
```
|
|
|
|
### 8. How to Add Support
|
|
|
|
**To add `ANTHROPIC_MODEL` support (3 small changes):**
|
|
|
|
**Change 1: Add to config.ts (after line 60)**
|
|
```typescript
|
|
export const ENV = {
|
|
// ... existing
|
|
ANTHROPIC_MODEL: "ANTHROPIC_MODEL",
|
|
} as const;
|
|
```
|
|
|
|
**Change 2: Add to cli.ts (after line 26)**
|
|
```typescript
|
|
// In parseArgs() function, after reading CLAUDISH_MODEL:
|
|
const anthropicModel = process.env[ENV.ANTHROPIC_MODEL];
|
|
if (!envModel && anthropicModel) {
|
|
config.model = anthropicModel; // Use as fallback
|
|
}
|
|
```
|
|
|
|
**Change 3: (Optional) Add to claude-runner.ts (after line 126)**
|
|
```typescript
|
|
// Set ANTHROPIC_MODEL in environment so other tools can read it
|
|
env[ENV.ANTHROPIC_MODEL] = modelId;
|
|
```
|
|
|
|
## Concrete Implementation Details
|
|
|
|
### Directory Structure
|
|
```
|
|
mcp/claudish/
|
|
├── src/
|
|
│ ├── index.ts # Main entry, orchestration
|
|
│ ├── cli.ts # Argument parsing (env vars on lines 22-34)
|
|
│ ├── config.ts # Constants, ENV object (lines 56-61)
|
|
│ ├── claude-runner.ts # Model → Claude Code (line 126)
|
|
│ ├── proxy-server.ts # Token tracking (line 805-816)
|
|
│ ├── types.ts # Interfaces
|
|
│ ├── transform.ts # API transformation
|
|
│ ├── logger.ts # Debug logging
|
|
│ ├── simple-selector.ts # Interactive prompts
|
|
│ ├── port-manager.ts # Port availability
|
|
│ └── adapters/ # Model-specific adapters
|
|
├── tests/
|
|
├── dist/ # Compiled output
|
|
└── package.json
|
|
```
|
|
|
|
### Critical Line Numbers
|
|
|
|
| File | Lines | Purpose |
|
|
|------|-------|---------|
|
|
| config.ts | 56-61 | ENV constant definition |
|
|
| cli.ts | 22-34 | Environment variable reading |
|
|
| cli.ts | 124-165 | API key handling |
|
|
| index.ts | 81-87 | Proxy creation with model |
|
|
| claude-runner.ts | 32-39 | Model context windows |
|
|
| claude-runner.ts | 85 | Temp settings file creation |
|
|
| claude-runner.ts | 120-127 | Environment variable assignment |
|
|
| claude-runner.ts | 60 | Status line command |
|
|
| proxy-server.ts | 805-816 | Token file writing |
|
|
|
|
### Environment Variable Chain
|
|
|
|
```
|
|
User Input (flags/env vars)
|
|
↓
|
|
cli.ts: parseArgs() → reads process.env
|
|
↓
|
|
ClaudishConfig object
|
|
↓
|
|
index.ts: runClaudeWithProxy()
|
|
↓
|
|
claude-runner.ts: env object construction
|
|
{
|
|
ANTHROPIC_BASE_URL: "http://127.0.0.1:3000",
|
|
CLAUDISH_ACTIVE_MODEL_NAME: "x-ai/grok-code-fast-1",
|
|
ANTHROPIC_API_KEY: "sk-ant-..."
|
|
}
|
|
↓
|
|
spawn("claude", args, { env })
|
|
↓
|
|
Claude Code process with modified environment
|
|
```
|
|
|
|
## Files to Examine
|
|
|
|
For implementation, focus on these files in order:
|
|
|
|
1. **`src/config.ts`** (69 lines)
|
|
- Where to define `ANTHROPIC_MODEL` constant
|
|
|
|
2. **`src/cli.ts`** (300 lines)
|
|
- Where to add environment variable parsing logic
|
|
|
|
3. **`src/claude-runner.ts`** (224 lines)
|
|
- Where model is communicated to Claude Code
|
|
- Where token file is read for status line
|
|
|
|
4. **`src/proxy-server.ts`** (58KB)
|
|
- Where tokens are written to file
|
|
- Good reference for token tracking mechanism
|
|
|
|
## Testing & Verification
|
|
|
|
To verify environment variable support works:
|
|
|
|
```bash
|
|
# Build claudish (from mcp/claudish directory)
|
|
cd mcp/claudish
|
|
bun run build
|
|
|
|
# Test with ANTHROPIC_MODEL
|
|
export ANTHROPIC_MODEL=openai/gpt-5-codex
|
|
export OPENROUTER_API_KEY=sk-or-v1-...
|
|
./dist/index.js "test prompt"
|
|
|
|
# Verify model is used by checking:
|
|
# 1. Status line shows "openai/gpt-5-codex"
|
|
# 2. No errors about unknown model
|
|
# 3. Claude Code runs with the specified model
|
|
```
|
|
|
|
## Key Insights
|
|
|
|
1. **Model ID is String-Based** - Not enum-restricted, any OpenRouter model ID accepted
|
|
2. **Environment Variables Flow Through Whole Stack** - Graceful inheritance pattern
|
|
3. **Token Tracking is Decoupled** - Separate file system allows status line to read without modifying proxy
|
|
4. **Temp Settings Pattern is Smart** - Each instance gets unique settings, no conflicts
|
|
5. **Configuration is Centralized** - ENV constant defined in one place, used everywhere
|
|
|
|
## Deliverables
|
|
|
|
Two comprehensive analysis documents created:
|
|
|
|
1. **`ai_docs/claudish-CODEBASE_ANALYSIS.md`** (14KB)
|
|
- Complete architecture overview
|
|
- All components explained
|
|
- Environment variable flow diagram
|
|
- Implementation recommendations
|
|
|
|
2. **`ai_docs/claudish-KEY_CODE_LOCATIONS.md`** (7.8KB)
|
|
- Line-by-line code references
|
|
- Variable scope table
|
|
- Implementation steps for adding ANTHROPIC_MODEL
|
|
- Debugging tips
|
|
|
|
## Recommendations
|
|
|
|
1. **Add ANTHROPIC_MODEL support** - Simple 3-line change (see "How to Add Support" section)
|
|
2. **Consider custom display names** - Allow mapping model ID to friendly name
|
|
3. **Document environment variables** - Update README with full variable reference
|
|
4. **Add integration tests** - Test env var overrides work correctly
|
|
|
|
---
|
|
|
|
**Exploration Completed:** November 15, 2025
|
|
**Files Examined:** 10+ TypeScript source files
|
|
**Analysis Documents:** 2 comprehensive guides (21.8 KB total)
|
|
**Claudish Version:** 1.3.1
|