alper
/
claudish
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
claudish/ai_docs/claudish-QUICK_REFERENCE.md

8.1 KiB
Raw Permalink Blame History

Claudish Codebase - Quick Reference Guide

One-Page Overview

What is Claudish?

A CLI tool that runs Claude Code with any OpenRouter model via a local Anthropic API-compatible proxy.

Version: 1.3.1 Location: mcp/claudish/ (in repository root) Language: TypeScript (Bun runtime)

Current Environment Variables

INPUT (User-Provided)         PROCESSED (Claudish-Set)
═══════════════════════════   ═══════════════════════════════════
OPENROUTER_API_KEY       →    ANTHROPIC_BASE_URL (proxy URL)
CLAUDISH_MODEL           →    CLAUDISH_ACTIVE_MODEL_NAME (model ID)
CLAUDISH_PORT            →    ANTHROPIC_API_KEY (placeholder)
ANTHROPIC_API_KEY        →    (inherited to Claude Code)

Missing Variables (Not Yet Implemented)

ANTHROPIC_MODEL              ← Would fallback model selection
ANTHROPIC_SMALL_FAST_MODEL   ← Would specify fast model

File Organization

src/
├── index.ts          ← Entry point, orchestration
├── cli.ts            ← Parse arguments & env vars
├── config.ts         ← Define ENV constants
├── types.ts          ← TypeScript interfaces
├── claude-runner.ts  ← Set up Claude Code environment
├── proxy-server.ts   ← Transform requests to OpenRouter
├── transform.ts      ← API format conversion
├── logger.ts         ← Debug logging
├── simple-selector.ts← Interactive prompts
├── port-manager.ts   ← Port availability
└── adapters/         ← Model-specific adapters

Data Flow

CLI Input (--model x-ai/grok-code-fast-1)
    ↓
parseArgs() in cli.ts
    ↓
config.model = "x-ai/grok-code-fast-1"
    ↓
createProxyServer(port, apiKey, config.model)
    ↓
runClaudeWithProxy(config, proxyUrl)
    ↓
env.CLAUDISH_ACTIVE_MODEL_NAME = "x-ai/grok-code-fast-1"
    ↓
spawn("claude", args, { env })
    ↓
Claude Code displays model in status line
    ↓
Status line script reads token file for context %

Key Code Locations (Line Numbers)

Component File Lines What It Does
ENV constants config.ts 56-61 Define all environment variables
Env var reading cli.ts 22-34 Parse CLAUDISH_MODEL, CLAUDISH_PORT
Model passing index.ts 81-87 Pass model to proxy creation
Env assignment claude-runner.ts 120-127 Set CLAUDISH_ACTIVE_MODEL_NAME
Status line claude-runner.ts 60 Bash script using model env var
Model contexts claude-runner.ts 32-39 Context window definitions
Token writing proxy-server.ts 805-816 Write token counts to file

Current Environment Variable Usage

OPENROUTER_API_KEY

  • Set by: User (required)
  • Read by: cli.ts, proxy-server.ts
  • Used for: OpenRouter API authentication

CLAUDISH_MODEL

  • Set by: User (optional)
  • Read by: cli.ts (line 23)
  • Default: Prompts user if not provided
  • Used for: Default model selection

CLAUDISH_PORT

  • Set by: User (optional)
  • Read by: cli.ts (line 28)
  • Default: Random port 3000-9000
  • Used for: Proxy server port selection

CLAUDISH_ACTIVE_MODEL_NAME

  • Set by: claude-runner.ts (line 126)
  • Read by: Status line bash script
  • Value: The OpenRouter model ID
  • Used for: Display in Claude Code status line

ANTHROPIC_BASE_URL

  • Set by: claude-runner.ts (line 124)
  • Read by: Claude Code
  • Value: http://127.0.0.1:{port}
  • Used for: Redirect API calls to proxy

ANTHROPIC_API_KEY

  • Set by: claude-runner.ts (line 138 or deleted in monitor mode)
  • Read by: Claude Code
  • Value: Placeholder or empty
  • Used for: Prevent auth dialog (proxy handles real auth)

Token Tracking System

Request to OpenRouter
    ↓ (proxy-server.ts accumulates tokens)
Response from OpenRouter
    ↓
writeTokenFile() at line 816
    ↓
/tmp/claudish-tokens-{PORT}.json
{
  "input_tokens": 1234,
  "output_tokens": 567,
  "total_tokens": 1801,
  "updated_at": 1731619200000
}
    ↓
Status line bash script reads file
    ↓
Calculates: (maxTokens - usedTokens) * 100 / maxTokens
    ↓
Displays as context percentage in status line

Model Context Windows (in tokens)

x-ai/grok-code-fast-1:                  256,000
openai/gpt-5-codex:                     400,000
minimax/minimax-m2:                     204,800
z-ai/glm-4.6:                          200,000
qwen/qwen3-vl-235b-a22b-instruct:      256,000
anthropic/claude-sonnet-4.5:           200,000
Custom/Unknown:                        100,000 (fallback)

How to Add ANTHROPIC_MODEL Support

3 Changes Needed:

  1. config.ts (1 line)

    ANTHROPIC_MODEL: "ANTHROPIC_MODEL",  // Add to ENV object

  2. cli.ts (3 lines after line 26)

    const anthropicModel = process.env[ENV.ANTHROPIC_MODEL];
if (!envModel && anthropicModel) {
  config.model = anthropicModel;
}

  3. claude-runner.ts (optional, 1 line after line 126)

    env[ENV.ANTHROPIC_MODEL] = modelId;

Testing Environment Variable Support

# Build (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"

# Verify: Status line should show openai/gpt-5-codex

Important Implementation Patterns

1. Centralized ENV Constant

// Define in one place
export const ENV = { CLAUDISH_ACTIVE_MODEL_NAME: "..." };

// Use everywhere
process.env[ENV.CLAUDISH_ACTIVE_MODEL_NAME]

2. Unique File Paths

// Prevents conflicts between parallel Claudish instances
const tokenFilePath = `/tmp/claudish-tokens-${port}.json`;
const tempPath = join(tmpdir(), `claudish-settings-${timestamp}.json`);

3. Safe Environment Inheritance

const env: Record<string, string> = {
  ...process.env,              // Keep existing
  ANTHROPIC_BASE_URL: proxyUrl, // Add/override specific
};

4. Model ID is String-Based

// Not enum-restricted - any OpenRouter model ID works
config.model: string = "x-ai/grok-code-fast-1" | "custom-model" | ...

Debugging Commands

# Enable debug logging
claudish --debug --model x-ai/grok-code-fast-1 "test"

# Monitor mode (see all API traffic)
claudish --monitor --model openai/gpt-5-codex "test"

# Check token file
cat /tmp/claudish-tokens-3000.json

# Check status line script
cat /tmp/claudish-settings-*.json | jq .statusLine.command

# Check environment variables
env | grep CLAUDISH

Architecture Decision: Why Temp Settings Files?

Problem: How to show model info in status line without modifying global Claude Code settings?

Solution: Create temporary settings file per instance

  • Each Claudish instance creates unique temp file
  • File contains custom status line command
  • Passed to Claude Code via --settings flag
  • Automatically cleaned up on exit
  • No conflicts between parallel instances
  • Global settings remain unchanged

Alternative Approach (Not Used):

  • Modify ~/.claude/settings.json - Would conflict with global config
  • Write to fixed file - Would conflict between parallel instances
  • Use Claude environment variables only - Status line wouldn't display model

Architecture Decision: Why Token File?

Problem: How to display real-time token usage in status line?

Solution: Token file shared between proxy and status line

  • Proxy accumulates tokens during conversation
  • Writes to /tmp/claudish-tokens-{PORT}.json after each request
  • Status line bash script reads file
  • No need to modify proxy response format
  • Decoupled from main communication protocol
  • Survives proxy shutdown (for final display)

Documents in This Directory

  • CODEBASE_ANALYSIS.md - 14KB complete architecture guide
  • KEY_CODE_LOCATIONS.md - 7.8KB code reference with line numbers
  • FINDINGS_SUMMARY.md - 10KB executive summary
  • QUICK_REFERENCE.md - This document (1-page overview)

Quick Reference Created: November 15, 2025 Claudish Version: 1.3.1 Total Lines of Analysis: 9600+