# kochc/opencode-llm-proxy architecture

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

- Interactive diagram: https://gitdiagram.com/kochc/opencode-llm-proxy
- Repository: https://github.com/kochc/opencode-llm-proxy

## Overview

opencode-llm-proxy is an OpenCode plugin that exposes a local HTTP gateway, translating OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, and Gemini requests into OpenCode prompts and returning responses in the caller’s format. The principal flow is request admission and model resolution, format adaptation, media preparation, OpenCode session execution, then response or stream formatting; tools are surfaced through an MCP bridge for client-side execution. It also documents model discovery, health, and metrics endpoints. The excerpts show shared orchestration in index.js but omit its route and stream internals, so uncertain internal call wiring is not expanded.

Main entry points: [`index.js`](https://github.com/kochc/opencode-llm-proxy/blob/main/index.js) (Proxy plugin), [`canonical-messages.js`](https://github.com/kochc/opencode-llm-proxy/blob/main/canonical-messages.js) (Canonical prompts), [`metrics.js`](https://github.com/kochc/opencode-llm-proxy/blob/main/metrics.js) (Metrics collection), [`remote-media.js`](https://github.com/kochc/opencode-llm-proxy/blob/main/remote-media.js) (Remote media)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["HTTP gateway"]
  node_gateway["Proxy plugin<br/>[index.js]"]
  node_auth["Access controls<br/>[index.js]"]
  node_api_formats["API endpoints<br/>[index.js]"]
  node_models["Model discovery<br/>[index.js]"]
end

subgraph group_translation["Request translation"]
  node_openai_chat["OpenAI Chat adapter"]
  node_openai_responses["Responses adapter"]
  node_anthropic["Anthropic adapter"]
  node_gemini["Gemini adapter"]
  node_canonical["Canonical prompts"]
  node_media["Remote media<br/>[remote-media.js]"]
end

subgraph group_execution["Model execution"]
  node_model_resolution["Model resolution<br/>[index.js]"]
  node_opencode["OpenCode SDK"]
  node_providers["Configured providers"]
  node_tool_bridge["MCP tool bridge<br/>[mcp-tool-bridge.js]"]
  node_response_streams["Response formatting<br/>[index.js]"]
end

subgraph group_operations["Operations"]
  node_health["Health endpoint<br/>[index.js]"]
  node_metrics["Metrics collection<br/>[metrics.js]"]
  node_metrics_endpoint["Metrics endpoint<br/>[index.js]"]
end

node_client(("API clients"))

node_client -->|"sends request"| node_gateway
node_gateway -->|"checks access"| node_auth
node_gateway -->|"dispatches request"| node_api_formats
node_api_formats -->|"adapts Chat"| node_openai_chat
node_api_formats -->|"adapts Responses"| node_openai_responses
node_api_formats -->|"adapts Messages"| node_anthropic
node_api_formats -->|"adapts Gemini"| node_gemini
node_openai_chat -->|"normalizes input"| node_canonical
node_openai_responses -->|"normalizes input"| node_canonical
node_anthropic -->|"normalizes input"| node_canonical
node_gemini -->|"normalizes input"| node_canonical
node_gateway -->|"resolves model"| node_model_resolution
node_gateway -->|"prepares media"| node_media
node_gateway -->|"renders prompt"| node_canonical
node_gateway -->|"starts session"| node_opencode
node_opencode -->|"routes generation"| node_providers
node_gateway -->|"registers tools"| node_tool_bridge
node_opencode -->|"streams events"| node_gateway
node_gateway -->|"formats output"| node_response_streams
node_response_streams -->|"returns response"| node_client
node_gateway -->|"serves model list"| node_models
node_models -->|"queries models"| node_opencode
node_gateway -->|"serves status"| node_health
node_gateway -->|"records activity"| node_metrics
node_metrics_endpoint -->|"serializes metrics"| node_metrics

click node_gateway "https://github.com/kochc/opencode-llm-proxy/blob/main/index.js"
click node_auth "https://github.com/kochc/opencode-llm-proxy/blob/main/index.js"
click node_api_formats "https://github.com/kochc/opencode-llm-proxy/blob/main/index.js"
click node_models "https://github.com/kochc/opencode-llm-proxy/blob/main/index.js"
click node_health "https://github.com/kochc/opencode-llm-proxy/blob/main/index.js"
click node_openai_chat "https://github.com/kochc/opencode-llm-proxy/blob/main/canonical-messages.js"
click node_openai_responses "https://github.com/kochc/opencode-llm-proxy/blob/main/canonical-messages.js"
click node_anthropic "https://github.com/kochc/opencode-llm-proxy/blob/main/canonical-messages.js"
click node_gemini "https://github.com/kochc/opencode-llm-proxy/blob/main/canonical-messages.js"
click node_canonical "https://github.com/kochc/opencode-llm-proxy/blob/main/canonical-messages.js"
click node_media "https://github.com/kochc/opencode-llm-proxy/blob/main/remote-media.js"
click node_model_resolution "https://github.com/kochc/opencode-llm-proxy/blob/main/index.js"
click node_tool_bridge "https://github.com/kochc/opencode-llm-proxy/blob/main/mcp-tool-bridge.js"
click node_response_streams "https://github.com/kochc/opencode-llm-proxy/blob/main/index.js"
click node_metrics "https://github.com/kochc/opencode-llm-proxy/blob/main/metrics.js"
click node_metrics_endpoint "https://github.com/kochc/opencode-llm-proxy/blob/main/index.js"

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_gateway,node_auth,node_api_formats,node_models,node_client toneBlue
class node_openai_chat,node_openai_responses,node_anthropic,node_gemini,node_canonical,node_media toneAmber
class node_model_resolution,node_opencode,node_providers,node_tool_bridge,node_response_streams toneMint
class node_health,node_metrics,node_metrics_endpoint toneRose
```

## Components

### HTTP gateway

- [Proxy plugin](https://github.com/kochc/opencode-llm-proxy/blob/main/index.js): `index.js`
- [Access controls](https://github.com/kochc/opencode-llm-proxy/blob/main/index.js): `index.js`
- [API endpoints](https://github.com/kochc/opencode-llm-proxy/blob/main/index.js): `index.js`
- [Model discovery](https://github.com/kochc/opencode-llm-proxy/blob/main/index.js): `index.js`

### Request translation

- [OpenAI Chat adapter](https://github.com/kochc/opencode-llm-proxy/blob/main/canonical-messages.js): `canonical-messages.js`
- [Responses adapter](https://github.com/kochc/opencode-llm-proxy/blob/main/canonical-messages.js): `canonical-messages.js`
- [Anthropic adapter](https://github.com/kochc/opencode-llm-proxy/blob/main/canonical-messages.js): `canonical-messages.js`
- [Gemini adapter](https://github.com/kochc/opencode-llm-proxy/blob/main/canonical-messages.js): `canonical-messages.js`
- [Canonical prompts](https://github.com/kochc/opencode-llm-proxy/blob/main/canonical-messages.js): `canonical-messages.js`
- [Remote media](https://github.com/kochc/opencode-llm-proxy/blob/main/remote-media.js): `remote-media.js`

### Model execution

- [Model resolution](https://github.com/kochc/opencode-llm-proxy/blob/main/index.js): `index.js`
- **OpenCode SDK**
- **Configured providers**
- [MCP tool bridge](https://github.com/kochc/opencode-llm-proxy/blob/main/mcp-tool-bridge.js): `mcp-tool-bridge.js`
- [Response formatting](https://github.com/kochc/opencode-llm-proxy/blob/main/index.js): `index.js`

### Operations

- [Health endpoint](https://github.com/kochc/opencode-llm-proxy/blob/main/index.js): `index.js`
- [Metrics collection](https://github.com/kochc/opencode-llm-proxy/blob/main/metrics.js): `metrics.js`
- [Metrics endpoint](https://github.com/kochc/opencode-llm-proxy/blob/main/index.js): `index.js`

### Other components

- **API clients**

## Connections

- API clients → Proxy plugin: sends request
- Proxy plugin → Access controls: checks access
- Proxy plugin → API endpoints: dispatches request
- API endpoints → OpenAI Chat adapter: adapts Chat
- API endpoints → Responses adapter: adapts Responses
- API endpoints → Anthropic adapter: adapts Messages
- API endpoints → Gemini adapter: adapts Gemini
- OpenAI Chat adapter → Canonical prompts: normalizes input
- Responses adapter → Canonical prompts: normalizes input
- Anthropic adapter → Canonical prompts: normalizes input
- Gemini adapter → Canonical prompts: normalizes input
- Proxy plugin → Model resolution: resolves model
- Proxy plugin → Remote media: prepares media
- Proxy plugin → Canonical prompts: renders prompt
- Proxy plugin → OpenCode SDK: starts session
- OpenCode SDK → Configured providers: routes generation
- Proxy plugin → MCP tool bridge: registers tools
- OpenCode SDK → Proxy plugin: streams events
- Proxy plugin → Response formatting: formats output
- Response formatting → API clients: returns response
- Proxy plugin → Model discovery: serves model list
- Model discovery → OpenCode SDK: queries models
- Proxy plugin → Health endpoint: serves status
- Proxy plugin → Metrics collection: records activity
- Metrics endpoint → Metrics collection: serializes metrics