# shanthropic/claude-adapter architecture

> Architecture diagram of the GitHub repository shanthropic/claude-adapter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shanthropic/claude-adapter
- Repository: https://github.com/shanthropic/claude-adapter

## Overview

Claude Adapter is a local authenticated proxy that lets Claude Code use OpenAI-compatible models. The standalone CLI guides setup, persists provider/model/tool-format configuration, starts the loopback server, and can update Claude Code settings. The request handler authenticates and validates Anthropic Messages requests, converts them for the configured provider, and returns either converted responses or translated SSE. The graph includes documented setup and protocol capabilities; some utility wiring is omitted where sampled source does not establish it.

Main entry points: [`src/server/handlers.ts`](https://github.com/shanthropic/claude-adapter/blob/main/src/server/handlers.ts) (Message Handler), [`src/cli.ts`](https://github.com/shanthropic/claude-adapter/blob/main/src/cli.ts) (Setup CLI), [`src/converters/request.ts`](https://github.com/shanthropic/claude-adapter/blob/main/src/converters/request.ts) (Request Conversion), [`src/converters/streaming.ts`](https://github.com/shanthropic/claude-adapter/blob/main/src/converters/streaming.ts) (SSE Conversion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Setup and Configuration"]
  node_cli["Setup CLI<br/>[cli.ts]"]
  node_config["Config and Settings<br/>[config.ts]"]
  node_metadata["Adapter Metadata<br/>[metadata.ts]"]
end

subgraph group_proxy["Local Proxy"]
  node_server["HTTP Server<br/>[index.ts]"]
  node_handlers["Message Handler<br/>[handlers.ts]"]
  node_validation["Request Validation<br/>[validation.ts]"]
  node_anthropic["Anthropic Types<br/>[anthropic.ts]"]
  node_providerutil["Provider Detection<br/>[provider.ts]"]
end

subgraph group_translation["Protocol Translation"]
  node_request["Request Conversion<br/>[request.ts]"]
  node_tools["Tool Conversion<br/>[tools.ts]"]
  node_xmlprompt["XML Tool Prompts<br/>[xmlPrompt.ts]"]
  node_response["Response Conversion<br/>[response.ts]"]
  node_streaming["SSE Conversion<br/>[streaming.ts]"]
  node_xmlstreaming["XML Stream Conversion<br/>[xmlStreaming.ts]"]
end

subgraph group_operations["Usage and Diagnostics"]
  node_usage["Token Usage<br/>[tokenUsage.ts]"]
  node_errors["Error Logging<br/>[errorLog.ts]"]
  node_storage["Private File Storage<br/>[fileStorage.ts]"]
  node_updates["Update Cache<br/>[update.ts]"]
end

node_operator(("Operator"))
node_claude(("Claude Code"))
node_provider(("OpenAI-Compatible API"))

node_operator -->|"runs setup"| node_cli
node_cli -->|"loads and saves"| node_config
node_cli -->|"initializes"| node_metadata
node_cli -->|"starts"| node_server
node_cli -->|"updates Claude settings"| node_config
node_claude -->|"sends messages"| node_server
node_server -->|"dispatches messages"| node_handlers
node_handlers -->|"validates"| node_validation
node_handlers -->|"detects endpoint"| node_providerutil
node_handlers -->|"converts request"| node_request
node_request -->|"converts tools"| node_tools
node_request -->|"adds XML instructions"| node_xmlprompt
node_request -->|"reads cached update"| node_updates
node_handlers -->|"sends completion request"| node_provider
node_provider -->|"returns completion"| node_handlers
node_handlers -->|"converts response"| node_response
node_handlers -->|"translates native stream"| node_streaming
node_handlers -->|"translates XML stream"| node_xmlstreaming
node_handlers -->|"records usage"| node_usage
node_handlers -->|"records errors"| node_errors
node_streaming -->|"records usage"| node_usage
node_streaming -->|"records errors"| node_errors
node_handlers -->|"returns Anthropic response"| node_claude

click node_cli "https://github.com/shanthropic/claude-adapter/blob/main/src/cli.ts"
click node_config "https://github.com/shanthropic/claude-adapter/blob/main/src/utils/config.ts"
click node_metadata "https://github.com/shanthropic/claude-adapter/blob/main/src/utils/metadata.ts"
click node_server "https://github.com/shanthropic/claude-adapter/blob/main/src/server/index.ts"
click node_handlers "https://github.com/shanthropic/claude-adapter/blob/main/src/server/handlers.ts"
click node_validation "https://github.com/shanthropic/claude-adapter/blob/main/src/utils/validation.ts"
click node_anthropic "https://github.com/shanthropic/claude-adapter/blob/main/src/types/anthropic.ts"
click node_request "https://github.com/shanthropic/claude-adapter/blob/main/src/converters/request.ts"
click node_tools "https://github.com/shanthropic/claude-adapter/blob/main/src/converters/tools.ts"
click node_xmlprompt "https://github.com/shanthropic/claude-adapter/blob/main/src/converters/xmlPrompt.ts"
click node_response "https://github.com/shanthropic/claude-adapter/blob/main/src/converters/response.ts"
click node_streaming "https://github.com/shanthropic/claude-adapter/blob/main/src/converters/streaming.ts"
click node_xmlstreaming "https://github.com/shanthropic/claude-adapter/blob/main/src/converters/xmlStreaming.ts"
click node_providerutil "https://github.com/shanthropic/claude-adapter/blob/main/src/utils/provider.ts"
click node_usage "https://github.com/shanthropic/claude-adapter/blob/main/src/utils/tokenUsage.ts"
click node_errors "https://github.com/shanthropic/claude-adapter/blob/main/src/utils/errorLog.ts"
click node_storage "https://github.com/shanthropic/claude-adapter/blob/main/src/utils/fileStorage.ts"
click node_updates "https://github.com/shanthropic/claude-adapter/blob/main/src/utils/update.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_config,node_metadata toneBlue
class node_server,node_handlers,node_validation,node_anthropic,node_providerutil toneAmber
class node_request,node_tools,node_xmlprompt,node_response,node_streaming,node_xmlstreaming,node_provider toneMint
class node_usage,node_errors,node_storage,node_updates toneRose
class node_operator,node_claude toneIndigo
```

## Components

### Setup and Configuration

- [Setup CLI](https://github.com/shanthropic/claude-adapter/blob/main/src/cli.ts): `src/cli.ts`
- [Config and Settings](https://github.com/shanthropic/claude-adapter/blob/main/src/utils/config.ts): `src/utils/config.ts`
- [Adapter Metadata](https://github.com/shanthropic/claude-adapter/blob/main/src/utils/metadata.ts): `src/utils/metadata.ts`

### Local Proxy

- [HTTP Server](https://github.com/shanthropic/claude-adapter/blob/main/src/server/index.ts): `src/server/index.ts`
- [Message Handler](https://github.com/shanthropic/claude-adapter/blob/main/src/server/handlers.ts): `src/server/handlers.ts`
- [Request Validation](https://github.com/shanthropic/claude-adapter/blob/main/src/utils/validation.ts): `src/utils/validation.ts`
- [Anthropic Types](https://github.com/shanthropic/claude-adapter/blob/main/src/types/anthropic.ts): `src/types/anthropic.ts`
- [Provider Detection](https://github.com/shanthropic/claude-adapter/blob/main/src/utils/provider.ts): `src/utils/provider.ts`

### Protocol Translation

- [Request Conversion](https://github.com/shanthropic/claude-adapter/blob/main/src/converters/request.ts): `src/converters/request.ts`
- [Tool Conversion](https://github.com/shanthropic/claude-adapter/blob/main/src/converters/tools.ts): `src/converters/tools.ts`
- [XML Tool Prompts](https://github.com/shanthropic/claude-adapter/blob/main/src/converters/xmlPrompt.ts): `src/converters/xmlPrompt.ts`
- [Response Conversion](https://github.com/shanthropic/claude-adapter/blob/main/src/converters/response.ts): `src/converters/response.ts`
- [SSE Conversion](https://github.com/shanthropic/claude-adapter/blob/main/src/converters/streaming.ts): `src/converters/streaming.ts`
- [XML Stream Conversion](https://github.com/shanthropic/claude-adapter/blob/main/src/converters/xmlStreaming.ts): `src/converters/xmlStreaming.ts`

### Usage and Diagnostics

- [Token Usage](https://github.com/shanthropic/claude-adapter/blob/main/src/utils/tokenUsage.ts): `src/utils/tokenUsage.ts`
- [Error Logging](https://github.com/shanthropic/claude-adapter/blob/main/src/utils/errorLog.ts): `src/utils/errorLog.ts`
- [Private File Storage](https://github.com/shanthropic/claude-adapter/blob/main/src/utils/fileStorage.ts): `src/utils/fileStorage.ts`
- [Update Cache](https://github.com/shanthropic/claude-adapter/blob/main/src/utils/update.ts): `src/utils/update.ts`

### Other components

- **Operator**
- **Claude Code**
- **OpenAI-Compatible API**

## Connections

- Operator → Setup CLI: runs setup
- Setup CLI → Config and Settings: loads and saves
- Setup CLI → Adapter Metadata: initializes
- Setup CLI → HTTP Server: starts
- Setup CLI → Config and Settings: updates Claude settings
- Claude Code → HTTP Server: sends messages
- HTTP Server → Message Handler: dispatches messages
- Message Handler → Request Validation: validates
- Message Handler → Provider Detection: detects endpoint
- Message Handler → Request Conversion: converts request
- Request Conversion → Tool Conversion: converts tools
- Request Conversion → XML Tool Prompts: adds XML instructions
- Request Conversion → Update Cache: reads cached update
- Message Handler → OpenAI-Compatible API: sends completion request
- OpenAI-Compatible API → Message Handler: returns completion
- Message Handler → Response Conversion: converts response
- Message Handler → SSE Conversion: translates native stream
- Message Handler → XML Stream Conversion: translates XML stream
- Message Handler → Token Usage: records usage
- Message Handler → Error Logging: records errors
- SSE Conversion → Token Usage: records usage
- SSE Conversion → Error Logging: records errors
- Message Handler → Claude Code: returns Anthropic response