CLAUDE.md

1# Proxy LLMs Claude Code Guide
2 
3This repository is a Cloudflare Worker proxy for OpenAI-compatible clients such as Cline. It receives local client requests, resolves friendly model aliases, and forwards requests to NVIDIA NIM.
4 
5## Project Shape
6 
7- `server.ts`: Hono app entrypoint, middleware setup, error handler, and Durable Object re-export only.
8- `controllers/`: Business logic controllers — each controller is a pure function that receives a Hono `Context` and returns a `Response`. Controllers are the single place where request processing, provider resolution, and response construction happen.
9  - `controllers/chat.ts`: `handleChatCompletions` — resolves provider, parses body, resolves model aliases, streams or buffers upstream responses, and collects metrics.
10  - `controllers/health.ts`: `handleHealth` — simple health-check endpoint.
11  - `controllers/legacy.ts`: `handleOpenAIModels`, `handleClaudeModels` — backward-compatible model listing endpoints.
12  - `controllers/models.ts`: `handleModels` — returns all models from all providers.
13  - `controllers/process.ts`: `handleProcess` — initiates the async Durable Object processing flow.
14- `routes/`: Thin route registration. Each file exports individual handler functions that **delegate immediately to controllers**; `routes/index.ts` registers them declaratively. Routes contain zero business logic.
15- `durable-objects/processor.ts`: `ProcessorDurableObject` class for the `/api/process` async flow.
16- `config/providers.ts`: provider endpoints, model aliases, model defaults, model listing, model resolution, and the single source of truth for `ProviderType`.
17- `interfaces/general.ts`: Worker bindings and shared request/response interfaces.
18- `errors/provider-error.ts`: provider error type that preserves upstream HTTP status codes.
19- `providers/provider-factory.ts`: factory for creating provider instances by name from the URL.
20- `providers/base-provider.ts`: shared provider logic for all AI backends.
21- `providers/nvidia-provider.ts`: NVIDIA NIM provider.
22- `providers/openrouter-provider.ts`: OpenRouter provider.
23- `providers/local-provider.ts`: LMStudio, LlamaCPP, and Ollama local providers.
24- `metrics/metrics-collector.ts`: request/response metrics collection for Analytics Engine.
25- `metrics/queries.ts`: Analytics Engine query helpers.
26- `utils/logger.ts`: Conditional logging utility. All debug/info/warn logs are gated by `DEBUG=true`; errors are always emitted. Used everywhere instead of raw `console.*`.
27- `__tests__/setup.ts`: Vitest setup file — mocks `crypto.randomUUID` for the Node.js test environment.
28- `wrangler.toml`: Cloudflare Worker and Durable Object configuration.
29 
30 
31## Architecture
32 
33- **Pattern**: Proxy — forward OpenAI-compatible requests to upstream LLM providers
34- **Primary responsibility**: Transparent request forwarding with model alias resolution
35- **Key concerns**: Model alias resolution, streaming response preservation, error status code forwarding, provider-agnostic interface, rate limiting, metrics collection
36- **Runtime**: Cloudflare Workers
37- **Primary language**: TypeScript
38 
39## Local Commands
40 
41- Install dependencies: `pnpm install`
42- Run locally: `pnpm run dev`
43- Typecheck: `pnpm run typecheck`
44- Run tests: `pnpm run test`
45- Run tests in watch mode: `pnpm run test:watch`
46- Run tests with coverage: `pnpm run test:coverage`
47- Deploy: `pnpm run deploy`
48 
49Prefer `pnpm run typecheck` after TypeScript changes. Run `pnpm run test` before finishing any non-trivial change. Do not run deploy commands unless the user explicitly asks.
50 
51## Runtime Behavior
52 
53- **Body-based routing**: The provider is extracted from the first segment of the `model` field in the request body
54  - Example: `POST /chat/completions` with body `{ "model": "nvidia/moonshotai/kimi-k2.6", ... }` routes to the `nvidia` provider
55  - Example: `POST /chat/completions` with body `{ "model": "claude/claude-3.5-sonnet", ... }` routes to the `claude` provider
56  - `provider` is the first segment of the `model` field before the first `/`. It must match a key in `ProviderConfigs` (nvidia, claude, google, openrouter, lmstudio, llamacpp, ollama).
57  - The remaining segments are the model name (alias or full upstream ID), which is resolved in `config/providers.ts`.
58  - The route handler looks up `ProviderConfigs[provider]` directly — no indirection or hardcoded format-to-config mapping.
59- **Claude API model mapping**: The `/messages` endpoint maps Claude model tiers (Opus, Sonnet, Haiku) to gateway models via environment variables:
60  - `ANTHROPIC_OPUS_MODEL` — model used when Claude Code sends an model with "opus"
61  - `ANTHROPIC_SONNET_MODEL` — model used when Claude Code sends a model with "sonnet"
62  - `ANTHROPIC_HAIKU_MODEL` — model used when Claude Code sends a model with "haiku"
63  - `ANTHROPIC_DEFAULT_MODEL` — fallback for any other model name
64  - Matching is case-insensitive (e.g. `claude-3-opus`, `CLAUDE-3-OPUS`, `claude-opus` all map to Opus)
65- **Legacy routes** (backward compatible): `GET /openai/v1/models`, `GET /claude/v1/models` still work for model discovery
66 
67- Friendly model IDs such as `glm4.7` or `kimi-k2-thinking` are accepted by the proxy and resolved to upstream IDs such as `z-ai/glm4.7` and `moonshotai/kimi-k2-thinking`.
68- The proxy should send the resolved model ID upstream, never the unresolved alias.
69- Streaming requests return the upstream SSE body directly to the client.
70- Non-streaming requests buffer and return JSON.
71- Durable Objects are for the `/api/process` async flow, not for Cline's OpenAI-compatible chat endpoint.
72- Metrics are collected via Cloudflare Analytics Engine (`ANALYTICS` binding).
73 
74 
75## Routing Pattern (Declarative)
76 
77- **`routes/*.ts` export only thin handler functions** — each handler is an `async (c: Context) => Response` function that delegates immediately to the corresponding controller in `controllers/`. No business logic, no conditionals, no validation.
78- **`routes/index.ts` is 100% declarative** — it imports all handlers and registers routes with `app.post('/', handler)` or `app.get('/', handler)`. No business logic, no conditionals, no validation.
79- **Business logic lives inside `controllers/`** or in modules imported by them (providers, utils).
80- **No `register*Routes(app)` functions** — the declarative registration in `routes/index.ts` replaces that indirection.
81- **Pattern check**: if `routes/index.ts` contains anything other than route registration (conditionals, validation, business logic), the routing pattern is violated.
82- **Pattern check**: if a handler in `routes/*.ts` contains more than a single call to a controller, the separation of concerns is violated.
83 
84## Development Rules
85 
86- **Controllers contain all business logic** — `controllers/*.ts` are the single source of truth for request processing, provider resolution, streaming/buffering, error handling, and metrics collection.
87- **Routes are thin wrappers** — `routes/*.ts` handlers should delegate to controllers immediately. If you find yourself adding logic in a route handler, extract it to the corresponding controller.
88- Keep model aliases and defaults in `config/providers.ts`.
89- Keep shared interfaces in `interfaces/general.ts`.
90- Preserve OpenAI-compatible passthrough fields such as `tools`, `tool_choice`, `response_format`, `stream_options`, `stop`, and `chat_template_kwargs`.
91- Do not log API keys, request bodies with secrets, or `.env` values.
92- Use the `logger` from `utils/logger.ts` for all logging. It respects the `DEBUG` environment variable so debug noise is controlled centrally. Never use raw `console.log` or `console.error`.
93- Do not commit `.env` or `.local`.
94- Avoid broad refactors in `server.ts`; extract focused modules when a block becomes mostly configuration or reusable utility logic.
95- If changing model resolution, verify both alias and full upstream model ID inputs still work.
96- If adding Claude model mapping, add the env var to `Env` in `interfaces/general.ts` and test in `__tests__/providers.test.ts`.
97- When adding a new provider:
98  1. Add the provider entry to `ProviderConfigs` in `config/providers.ts` (key, models, endpoint, format).
99  2. Add `case` in `createProvider()` in `providers/provider-factory.ts`.
100  3. Add credentials to `Env` in `interfaces/general.ts`.
101  4. `ProviderType` is derived automatically from `ProviderConfigs` keys — no need to edit `interfaces/provider.ts`.
102- Body-based routing: `POST /chat/completions` — the provider is extracted from the first segment of the `model` field in the request body (e.g., `"nvidia/moonshotai/kimi-k2.6"` → provider = `nvidia`). The route handler looks up `ProviderConfigs[provider]` directly. No hardcoded format-to-config mapping.
103 
104## Development Workflow
105 
1061. **Review the request, think about it, and brainstorm**
107   - Use `/superpowers:brainstorm` for new features
108   - Use `/superpowers:systematic-debugging` for bug fixes
1092. **Ask clarifying questions** (when needed)
1103. **Think hard and make a plan**
1114. **Only when we agree on a plan, create a detailed to-do list** using the `task_progress` parameter
1125. **If writing code, add these review tasks at the end of the to-do list:**
113   - A. Run `pnpm run typecheck`
114   - B. Run `pnpm run test`
115   - C. Review against routing pattern: `routes/index.ts` must be declarative
116   - D. Run the `security-code-reviewer` sub-agent
1176. **Once we agree on the to-do list, start implementation**
1187. **During implementation:**
119   - Keep things simple and stick to the requested scope
120   - Do NOT over-complicate things
121   - Do NOT add unnecessary complexity
1228. **At the end, verify:**
123   - All tests pass (`pnpm run test`)
124   - TypeScript compiles cleanly (`pnpm run typecheck`)
125   - Routing pattern is respected (declarative `routes/index.ts`)
126 
127## Security
128 
129- Sensitive files: `.env`, `.local`, `wrangler.toml` — never commit or expose
130- Secret handling: Environment variables only, never hardcoded or committed. Use a secrets manager (Infisical, 1Password) and inject at runtime with `infisical run -- pnpm run dev` or `op run -- pnpm run dev`
131- Auth scope: Multiple upstream providers (NVIDIA, OpenRouter, LMStudio, etc.)
132- **Never store plaintext secrets in `.env` or `.env.dev` files** — use secret references like `infisical://project/env/api-key`
133 
134### Supply-chain hardening controls
135 
136| Control | File | Description |
137|---|---|---|
138| Ignore lifecycle scripts | `.npmrc` | `ignore-scripts=true` prevents arbitrary code execution during install |
139| Block git deps | `.npmrc` | `allow-git=none` rejects git-source dependencies |
140| Install cooldown | `.npmrc` | `min-release-age=30` blocks packages newer than 30 days |
141| pnpm trust policy | `pnpm-workspace.yaml` | `trustPolicy: no-downgrade` refuses versions with weaker trust signals |
142| Strict dep builds | `pnpm-workspace.yaml` | `strictDepBuilds: true` fails install on unapproved build scripts |
143| Block exotic subdeps | `pnpm-workspace.yaml` | `blockExoticSubdeps: true` blocks git/tarball in transitive deps |
144| Frozen lockfile check | `package.json` | `corepack pnpm install --lockfile-only --frozen-lockfile --ignore-scripts --optimistic-repeat-install` validates lockfile consistency |
145| Dependabot cooldown | `.github/dependabot.yml` | 7-day cooldown before auto-upgrading dependencies |
146| CODEOWNERS | `.github/CODEOWNERS` | Mandatory review for lockfiles and package manager config |
147| CI hardening | `.github/workflows/ci-cd.yaml` | Deterministic install (`pnpm install --frozen-lockfile --prefer-offline`) + lockfile validation |
148| Dev container | `.devcontainer/devcontainer.json` | Isolated environment with `--cap-drop=ALL` and `--no-new-privileges` |
149 
150### Pre-install security audit
151 
152Before installing new packages, audit them with:
153 
154```bash
155# npq — pre-install security auditor
156pnpm install -g npq
157pnpq install <package>
158 
159# Socket Firewall — real-time malicious package blocker
160pnpm install -g sfw
161sfw pnpm install <package>
162```
163 
164### Secure local development
165 
166- Use the provided [Dev Container](.devcontainer/devcontainer.json) for isolated development
167- The container drops all capabilities, disables proto pollution, and enforces `ignore-scripts` and `allow-git=none`
168- Run `pnpm install --frozen-lockfile --prefer-offline` instead of `pnpm install` for deterministic installs
169 
170### CI/CD security
171 
172- CI uses `pnpm install --frozen-lockfile --prefer-offline` for deterministic installs
173- Lockfile consistency is validated with pnpm before the rest of `validate`
174- Dependabot PRs have a 7-day cooldown to avoid compromised fresh releases
175- CODEOWNERS requires explicit review for lockfiles and package manager config
176 
177 
178## Logging
179 
180All code must use the `logger` from `utils/logger.ts` instead of raw `console.*` calls. The logger respects the `DEBUG` environment variable:
181 
182```typescript
183import { logger } from '../utils/logger'
184 
185logger.debug('Detailed debug output', details)        // only when DEBUG=true
186logger.info('General info', context)                  // only when DEBUG=true
187logger.warn('Warning condition', details)             // only when DEBUG=true
188logger.error('Something broke', error)                  // always visible
189logger.logUpstreamConfig(requestId, payload)          // sanitized, only when DEBUG=true
190```
191 
192- `debug()`, `info()`, `warn()` — suppressed when `DEBUG=false` (default in production)
193- `error()` — always visible, never suppressed
194- `logUpstreamConfig()` — strips `messages` from payload, logs count only; only when `DEBUG=true`
195 
196Set `DEBUG=true` in your `.env` or environment to enable debug output.
197 
198## Testing
199 
200- Tests live in `__tests__/*.test.ts` and run with Vitest.
201- The setup file `__tests__/setup.ts` mocks `globalThis.crypto.randomUUID` for Node.js compatibility.
202- **Critical import gotcha**: Because `server.js` (legacy) exists alongside `server.ts`, test imports **must** use the `.ts` extension (e.g., `from '../server.ts'`). Without it, Vitest resolves to `server.js` at runtime, which only exports `ProcessorDurableObject` and `default`, causing `TypeError: createResponse is not a function` and similar errors.
203- Always run `pnpm run test` after modifying `server.ts`, `config/providers.ts`, or any test file.
204 
205## Custom Slash Commands
206 
207- `/pattern-review` — Review changes for consistency with local patterns and architectural decisions
208- `/security-review` — Review changes for secret handling, unsafe commands, and security risks
209