#llm_interop

• Protocol bridging across three API surfaces -- accepts Anthropic Messages, OpenAI Chat Completions, and OpenAI Responses API requests and translates them to whichever format the backend expects
• Run AI developer tools against any backend -- use Claude Code, Codex CLI, or the Claude Agent SDK with Ollama, OpenAI, Gemini, or any OpenAI-compatible API by simply changing the gateway config
• Model aliasing and parameter harmonization -- rewrites model names (e.g., claude-sonnet-4-6 to llama3) and normalizes parameters like max_output_tokens to max_tokens so clients and backends speak the same language

#Architecture

#Architecture Diagram

AI Tool / Client                   MoonBit LLM Gateway                     LLM Backend
==================          ==============================          =======================

Claude Code / SDK  ----\
  POST /v1/messages     |
                        |    +----------------------------+
OpenAI Agents SDK  -----|    |        GatewaySurface      |
  POST /v1/responses    |--->|  (Anthropic|OpenAI|Gemini  |
                        |    |           |Codex)          |
Codex CLI / VS Code ----|    +------------+---------------+
  JSON-RPC stdio        |                 |
                        |    +------------v---------------+
MCP Client  -----------/     |     Dialect Transforms     |
  MCP stdio                  |  Anthropic <-> OpenAI      |
                             |  Gemini    <-> OpenAI      |
                             |  Responses -> Completions  |
                             |  (harmony pipeline)        |
                             +------------+---------------+
                                          |
                             +------------v---------------+
                             |   Model Aliasing + Routing |
                             |  claude-sonnet-4-6 -> llama3 |
                             +------------+---------------+
                                          |
                              +-----------+-----------+
                              |           |           |
                              v           v           v
                           OpenAI     Anthropic    Ollama
                           Gemini     Bedrock      Codex
                           Copilot    claude mcp   ...

#Core Concepts

#Project Structure

llm_interop/
├── src/                              Library packages
│   ├── gateway/                      Core gateway: config, types, dialect dispatch, routing
│   ├── dialects/                     Protocol transform implementations
│   │   ├── anthropic/                Anthropic Messages API transforms and accumulator
│   │   ├── openai/                   OpenAI Chat Completions + Responses API transforms
│   │   ├── gemini/                   Google Gemini GenerativeAI transforms
│   │   ├── harmony/                  Harmony (gpt-oss) Chat Completions accumulator
│   │   ├── codex/                    Codex app-server JSON-RPC transforms
│   │   └── claude_mcp/              `claude mcp serve` subprocess transforms
│   ├── types/                        Shared message types (ToolCallRequest, etc.)
│   ├── client/                       HTTP client with multi-provider integration tests
│   ├── sse/                          SSE parser (JSONL) and serializer
│   ├── jsonrpc/                      JSON-RPC 2.0 pure protocol layer
│   ├── mcp/                          MCP (Model Context Protocol) pure protocol layer
│   ├── spawn/                        Shell-safe command builder for subprocess execution
│   ├── interop/                      Fixture-based protocol interop tests
│   │   └── util/                     Test utilities
│   ├── utils/                        JSON manipulation and string helpers
│   └── wasm-gc/                      WebAssembly (wasm-gc) build artifacts
│       └── release/                  Release binaries
├── cmd/                              Executable entry points
│   ├── gateway-native/               HTTP gateway server (native target)
│   ├── app-server/                   Codex app-server frontend (JSON-RPC over stdio)
│   ├── claude-mcp-server/            MCP server frontend (emulates `claude mcp serve`)
│   └── js-test-demo/                 JS target test/demo runner
└── examples/                         Usage examples and integration guides

#Getting Started

#Quick Start

#Prerequisites

• MoonBit toolchain -- install from https://www.moonbitlang.com/download/
• Ollama -- install from https://ollama.com and pull a model:

ollama pull llama3

#Build the gateway

cd cmd/gateway-native
moon build --target native

#Run: Claude Code through the gateway to Ollama

cd cmd/gateway-native
moon run --target native . -- \
  --dialect anthropic \
  --config ../../examples/claude-agent-sdk/gateway-config.json

ANTHROPIC_BASE_URL=http://localhost:18080 \
ANTHROPIC_AUTH_TOKEN=dummy \
claude --model sonnet --print "What is 2+2?"

#Usage

#Dialects

#Gateway configuration

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "modelsFromEndpoint": false,
      "modelPatterns": ["llama", "claude-"],
      "modelAliases": {
        "claude-sonnet-4-6": "llama3"
      },
      "models": [
        {
          "id": "llama3",
          "name": "Llama 3",
          "reasoning": false,
          "input": ["text"],
          "contextWindow": 8192,
          "maxTokens": 4096
        }
      ]
    }
  },
  "server": {
    "port": 18080,
    "host": "0.0.0.0"
  }
}

#Provider fields

#Server fields

#Example: Claude Code + Ollama

# 1. Pull a model
ollama pull llama3

# 2. Start the gateway with anthropic dialect
cd cmd/gateway-native
moon run --target native . -- \
  --dialect anthropic \
  --config ../../examples/claude-agent-sdk/gateway-config.json

# 3. Run Claude Code against the local gateway
ANTHROPIC_BASE_URL=http://localhost:18080 \
ANTHROPIC_AUTH_TOKEN=dummy \
claude --model sonnet --print "What is 2+2?"

#Example: Codex CLI + Ollama

# 1. Pull a model
ollama pull llama3

# 2. Start the gateway
cmd/gateway-native/_build/native/debug/build/llm_interop-gateway-native.exe \
  -c examples/codex/gateway-config.json

# 3. Run Codex CLI against the gateway
codex -m "llama3" \
  -c 'model_providers.gw.name="Gateway"' \
  -c 'model_providers.gw.base_url="http://localhost:18080/v1"' \
  -c 'model_provider="gw"' \
  exec "List the files in the current directory"

#Packages

#API Surfaces

#Core Packages

#Command Targets

#References

#Design Documents

• OpenAI Harmony Response Format -- Responses API dialect design
• Codex App Server Protocol -- Codex CLI integration protocol
• Claude Code MCP Server -- MCP server for Claude Code
• Claude MCP Serve Tools -- MCP tool serving specification

#Examples

• Codex CLI Example -- Using llm_interop with the Codex CLI
• Claude Agent SDK Example -- Using llm_interop with the Claude Agent SDK

#Development

#Build and Test

make check          # Type-check for native and js targets
make test           # Run unit tests for native and js targets
make info           # Generate .mbti interface files
make verify         # Run check + test + info (full local verification)

#Individual Target Commands

make check-native   # Type-check native only
make check-js       # Type-check js only
make test-native    # Test native only
make test-js        # Test js only

#Integration Tests

make test-integration PROVIDER=anthropic   # Requires ANTHROPIC_API_KEY
make test-integration PROVIDER=openai      # Requires OPENAI_API_KEY
make test-integration PROVIDER=groq        # Requires GROQ_API_KEY

#Native Gateway

make gateway        # Run the native gateway with gateway-config.json

#JS Target Demo

make demo-js        # moon run --target js cmd/js-test-demo
make test-js-demo   # moon test --target js cmd/js-test-demo

#License