Agent-bridge – an OpenAI-compatible API for headless coding-agent CLIs

An independent project called agent-bridge, a Go HTTP server released under the GNU GPL v3 or later, exposes an OpenAI-compatible API at /v1/chat/completions and /v1/models and fulfils each request by running the official Claude Code CLI in headless mode (claude -p --output-format stream-json). The server also supports the OpenAI Codex CLI (codex exec --json) and the Kimi Code CLI (kimi acp, over the Agent Client Protocol) as backends, letting clients such as LangChain, LlamaIndex, CrewAI, AutoGen and the OpenAI Python, Node and Go SDKs switch to it by changing only base_url, api_key and model. It requires the claude CLI version 2.1.128 or later plus one interactive login, ships as a single binary for Linux, macOS and Windows on amd64 and arm64, and is not developed, endorsed or supported by Anthropic.

English · Italiano https://github.com/R3n3r0/agent-bridge/blob/main/README.it.md agent-bridge is an HTTP server written in Go that exposes an OpenAI-compatible API /v1/chat/completions , /v1/models and fulfils every request by running the official Claude Code CLI in headless mode claude -p --output-format stream-json . It can also run the OpenAI Codex CLI codex exec --json or the Kimi Code CLI kimi acp , over the Agent Client Protocol instead, with the same API: see the Codex backend https://github.com/R3n3r0/agent-bridge/blob/main/docs/codex.md and the Kimi backend https://github.com/R3n3r0/agent-bridge/blob/main/docs/kimi.md . Any client or framework that speaks OpenAI can use it by changing only base url , api key and model : chat, streaming, function calling tool calling and image input work with the official SDKs unchanged. In short: an OpenAI-compatible API server, proxy and gateway for Claude Code . It lets OpenAI-based multi-agent systems, ReAct orchestrators and frameworks that accept a custom OpenAI base url for example LangChain, LlamaIndex, CrewAI, AutoGen or the OpenAI SDKs for Python, Node and Go use Claude Code headless as a drop-in chat completions model or as a coding agent, with tool calling, MCP servers, sessions, streaming SSE and per-agent models. The same server is an OpenAI-compatible API, proxy and gateway for the OpenAI Codex CLI and for the Kimi Code CLI Moonshot AI, Kimi K2 , and an ACP Agent Client Protocol client. Independent project. agent-bridge is not developed, endorsed or supported by Anthropic. It runs the official claude binary installed on the machine, without modifying it, and never accesses its credentials. - Single binary, Go standard library only at runtime. - Linux, macOS and Windows amd64 and arm64 . - Same build for development subscription login and production API key . - OpenAI function calling tools , tool calls , streaming included. - Image input image url parts: data URLs and http s URLs . - Three CLI backends: the default one, the OpenAI Codex CLI backend: "codex" , see docs/codex.md https://github.com/R3n3r0/agent-bridge/blob/main/docs/codex.md and the Kimi Code CLI backend: "kimi" , see docs/kimi.md https://github.com/R3n3r0/agent-bridge/blob/main/docs/kimi.md . - Free software, licensed under the GNU GPL v3 or later. | | As a model | As an agent on the server | |---|---|---| | Who defines the agent | Your client or platform: system , tools , model choice | The bridge configuration file | | Available tools | Only the functions the client sends in tools , executed by the client | CLI tools on the server machine files, commands, search, MCP servers , plus any client functions | | model | bridge/opus , bridge/sonnet , bridge/haiku , bridge/<model name | The name of the configured agent | | Configuration | None | JSON file | | Section | Using it as a model using-it-as-a-model | Agents on the server agents-on-the-server | "Tools" therefore come in two kinds, both supported: - client functions OpenAI function calling : defined and executed by the client; the model calls them through tool calls ; - agent tools : Read , Edit , Bash , MCP servers… executed by the CLI on the server, within the agent's permissions; the client only sees the final result. Prerequisite: the claude CLI installed, version 2.1.128 or later , and one interactive login claude . go install github.com/r3n3r0/agent-bridge/cmd/agent-bridge@latest AGENT BRIDGE AUTH MODE=subscription agent-bridge curl -s http://127.0.0.1:8787/v1/chat/completions \ -d '{"model":"bridge/haiku","messages": {"role":"user","content":"Hello "} }' Without a configuration file the server listens on 127.0.0.1:8787 and accepts the models bridge/opus , bridge/sonnet , bridge/haiku and bridge/<model name the name after the prefix is passed to the CLI as is; the bridge/ prefix can be changed with builtin prefix . They are chat-only models: no server tools, an empty temporary working directory, but they accept client functions and images. Alternatively, download a binary from the releases page archives and checksums.txt for every platform . This is the scenario of a platform that already has its own agents, graph and lifecycle for example a ReAct system : the bridge behaves like an OpenAI model and the agent is the one defined in the platform. | In the platform | In the request | |---|---| | Agent instructions | system message | | Agent tools | tools | | Model | bridge/<alias or model name | Two options make the bridge stateless and make the platform's agent the only agent. Set them in the configuration, or per request with a header: | Configuration key | Header | Effect | |---|---|---| | client tools.mode: "stateless" | X-Agent-Bridge-Tool-Mode: stateless | After returning tool calls the process exits: every request is one step of the graph and the history sent by the client is the only source of truth. Branches, retries and checkpoints stay in the platform | | system messages: "replace" | X-Agent-Bridge-System-Mode: replace | system messages become the effective system prompt instead of the CLI one, at every step. With append they are added to it | Recommended configuration for this scenario: { "client tools": { "mode": "stateless" }, "system messages": "replace" } In this scenario do not send X-Session-Id : every request starts a new process with the full history. It costs some latency per step, in exchange for no hidden state in the bridge. Functions defined by the client with tools work as with the OpenAI API: the model answers with tool calls and finish reason: "tool calls" , the client runs the functions and sends the results back as role: "tool" messages, and the model continues. It also works when streaming delta.tool calls and without session headers. r = client.chat.completions.create model="bridge/sonnet", messages=messages, tools=tools while r.choices 0 .finish reason == "tool calls": messages.append r.choices 0 .message for call in r.choices 0 .message.tool calls: messages.append {"role": "tool", "tool call id": call.id, "content": run call.function.name, call.function.arguments } r = client.chat.completions.create model="bridge/sonnet", messages=messages, tools=tools Complete example: examples/python/tools.py https://github.com/R3n3r0/agent-bridge/blob/main/examples/python/tools.py . Supported: tools type function , tool choice auto , none , required , a specific function , parallel tool calls parallel calls returned together and the deprecated functions / function call format. How it works. Client functions are offered to the CLI as tools of a standard MCP server, served by the bridge itself internal mcp-tools subcommand . When the model calls one, the bridge returns the call to the client. Then, depending on client tools.mode : | Mode | What happens | When to choose it | |---|---|---| | stateful default | The process waits; the request carrying the results is recognized by its tool call id s and the same process resumes where it stopped | Simple clients: lower latency between steps | | stateless | The process exits; the request carrying the results starts a new process with the full history | Orchestrators with their own state see Using it as a model using-it-as-a-model | Differences to be aware of: - tool choice other than auto / none and parallel tool calls: false are expressed as instructions to the model: the model follows them, but they are not hard constraints as in the OpenAI API. Function parameters schemas and strict also guide the model but are not enforced. - In stateful mode the waiting process holds a concurrency slot. If the results do not arrive within client tools.wait timeout seconds default 600 the process is stopped; a later request with the results starts a new process from the full history, so it still works. - With the deprecated functions format results carry no id: every call ends the process, as in stateless mode. - In a tool calls response usage covers only the model's last message; turn totals are in the logs and in /stats . Messages can contain image url parts, as in the OpenAI API, with any model: r = client.chat.completions.create model="bridge/sonnet", messages= {"role": "user", "content": {"type": "text", "text": "What is in this picture?"}, {"type": "image url", "image url": {"url": "data:image/png;base64,..."}}, } - Sources : data: URLs base64 and http s URLs, which the bridge downloads. Downloads from non-public addresses loopback, private networks, cloud metadata are refused unless images.allow private networks is set; images.fetch urls: false accepts only data: URLs. - Formats : PNG, JPEG, GIF, WebP, recognized from the content. Up to images.max count images per request default 20 and images.max bytes each default 5 MB ; the whole input, images included, must stay within 9 MB. - How : images are sent to the CLI as image blocks of a structured message --input-format stream-json ; the text refers to them as image 1 , image 2 … in order. Requests without images keep plain-text input. - In a resumed session only the images of the new messages are sent; earlier ones are already in the session. images.enabled: false rejects images with 400 unsupported content . The bridge drives the CLI, not the model API directly, so it supports the OpenAI parameters the CLI can express, and emulates two more: | OpenAI parameter | How | Fidelity | |---|---|---| | reasoning effort | CLI --effort ; none / minimal become low , xhigh and max are accepted as an extension | Direct | | response format json object , json schema | CLI --json-schema : the answer is validated against the schema and returned as compact JSON in content | Direct, validated | | max tokens , max completion tokens | CLAUDE CODE MAX OUTPUT TOKENS for the process | Partial: limits every model response of the turn, not the turn total; finish reason is not set to length | | stop string or up to 4 | The final text is cut at the first occurrence | Emulated: the model still generates the full answer; never applied to response format JSON or to progress texts | | n 1-8 | n independent processes in parallel, one choice each, also when streaming | Emulated: costs n times; no session resume, and client functions run stateless | | temperature , top p , seed , logprobs , presence penalty , frequency penalty , logit bias | — | Accepted and ignored: the CLI has no equivalent | If response format cannot be satisfied the CLI gives up after its retries, or ends without structured output , the request fails with 502. A JSON file maps a model name to an agent: model, system prompt, CLI tools, permissions and working directory. Use it when the agent must work on the server machine, for example on a repository. { "agents": { "reviewer": { "model": "opus", "system prompt": "You are a strict reviewer. Do not modify files.", "allowed tools": "Read", "Grep", "Glob" , "cwd": "/srv/project" }, "coder": { "model": "sonnet", "allowed tools": "Read", "Edit", "Write", "Bash go test " , "permission mode": "acceptEdits", "cwd": "/srv/project" } } } agent-bridge check-config -config agents.json validate and print the resolved agents AGENT BRIDGE AUTH MODE=subscription agent-bridge -config agents.json The client picks the agent with the model field: python from openai import OpenAI client = OpenAI base url="http://127.0.0.1:8787/v1", api key="unused" r = client.chat.completions.create model="reviewer", messages= {"role": "user", "content": "Review the error handling."} , extra headers={"X-Session-Id": "review-42"}, print r.choices 0 .message.content An agent on the server can also receive client functions in tools : it will use both its own tools and those. Full reference: docs/configuration.md https://github.com/R3n3r0/agent-bridge/blob/main/docs/configuration.md . Annotated example: examples/agents.example.json https://github.com/R3n3r0/agent-bridge/blob/main/examples/agents.example.json . - Without X-Session-Id OpenAI behavior : every request starts a new process; the history sent by the client is turned into a single prompt. - With X-Session-Id or the user field : the same key resumes the CLI session with --resume , and the CLI receives only the new messages user messages and tool results after the assistant's last answer. Faster in long conversations. The key, generated when missing, is always returned in the X-Session-Id response header. - system messages are placed at the top of the prompt system messages: "prompt" , default : in a resumed session only those of the first turn count. With append or replace they are passed as the system prompt and apply to every turn. - Answers to tool calls in stateful mode resume the waiting process through the tool call id s, regardless of the session. The mode is chosen only by configuration, with the mandatory AGENT BRIDGE AUTH MODE variable: | Mode | Use | Credentials | |---|---|---| | subscription | Development on your own machine | Login done with claude ; ANTHROPIC API KEY and ANTHROPIC AUTH TOKEN must not be set | | api | Production and shared instances | ANTHROPIC API KEY required Claude Console key | The server refuses to start if the mode and the environment are inconsistent. In subscription mode the API key variables are removed from the child process environment anyway, and if the CLI reports using an API key the server logs an error on every turn. Every turn records tokens and cost logs, optional usage log file, /stats , /metrics . In subscription mode cost usd is an estimate computed by the CLI at API prices, not a charge : it helps forecast what production with an API key will cost. compose.yaml runs the bridge with all three CLIs, one service per backend ports 8787, 8788 and 8789 on the host's loopback , sharing one home volume for the CLIs' logins: make up creates .env with a random API key, builds, starts, prints the addresses make admin opens the login page make smoke one request to every service make help lists the other targets logs, doctor, terminal logins, update, reset . Without make: cp .env.example .env , set AGENT BRIDGE API KEY , docker compose up -d . Then log in to the CLIs from the admin page, http://127.0.0.1:8787/admin : it runs each CLI's official login flow on the server and shows its link and one-time code or a box to paste the code back . The CLIs keep the credentials; the bridge never reads them. Details: docs/docker.md https://github.com/R3n3r0/agent-bridge/blob/main/docs/docker.md . With backend: "codex" or -backend codex , AGENT BRIDGE BACKEND=codex every turn runs codex exec --json instead of the default CLI. The API, sessions, function calling, images, structured output and reasoning effort work the same way; built-in models become bridge/default the model configured in Codex and bridge/<model ; agents with tools use a sandbox read-only , workspace-write , danger-full-access instead of permission mode and allowed tools . Authentication: codex login in subscription mode, CODEX API KEY in api mode. codex login AGENT BRIDGE AUTH MODE=subscription agent-bridge -backend codex Full mapping, agent fields and differences: docs/codex.md https://github.com/R3n3r0/agent-bridge/blob/main/docs/codex.md . With backend: "kimi" or -backend kimi , AGENT BRIDGE BACKEND=kimi every turn runs kimi acp , the Kimi Code CLI as an Agent Client Protocol agent, with the bridge as the ACP client. The API, sessions, function calling, images, structured output and reasoning effort work the same way; built-in models become bridge/default the default model of Kimi Code and bridge/<model ; the bridge answers the CLI's permission requests from allowed tools , disallowed tools and permission mode default , plan , auto , yolo . Authentication: kimi login in subscription mode, KIMI MODEL NAME and KIMI MODEL API KEY in api mode. ACP reports no token usage or cost. kimi login --region global kimi.ai; mainland-cn for kimi.com AGENT BRIDGE AUTH MODE=subscription agent-bridge -backend kimi Full mapping, agent fields and differences: docs/kimi.md https://github.com/R3n3r0/agent-bridge/blob/main/docs/kimi.md . agent-bridge is a tool: whoever uses it remains responsible for complying with the terms of their plan. In short: 1. No access to credentials. The code never reads, copies, stores, logs or forwards credential files or tokens. Login happens only through the CLI's official flow, and the subscription token is never used to call the API directly. 2. One subscription, one user. In subscription mode the server must serve only the account holder, on their own machine. The default configuration listens on loopback only; remote access must be enabled explicitly and is meant for reaching your own instance from your own laptop e.g. a personal VPN , not for other users. 3. Shared instances only with an API key. An instance used by several people e.g. a lab or a team must run in api mode with the owner's key, without reselling or brokering costs. References, to be checked again because the rules may change : An agent on the server with tools enabled can read, write and run commands: whoever reaches the server has the equivalent of a restricted shell. Defaults are closed and every opening is explicit. - Network. Listens on 127.0.0.1:8787 by default. A non-loopback address requires allow remote: true or -allow-remote and AGENT BRIDGE API KEY . There is no built-in TLS: for remote access use a reverse proxy with TLS, an SSH tunnel or a VPN. - Client authentication. With AGENT BRIDGE API KEY set, /v1/ , /stats and /metrics require Authorization: Bearer <key constant-time comparison . /healthz and /readyz stay open. - CORS is disabled; enable it with an exact list of origins cors origins , no wildcards. - bridge/ models are always chat-only: no server tools, in any mode. - Client functions are executed only by the client, never on the server. Calls go through an internal broker on 127.0.0.1 with a random port and a different token for every turn; the turn's files are private and removed at the end. - Per-request overrides X-Agent-Cwd , X-Agent-Allowed-Tools , X-Agent-System-Prompt are rejected with 403 unless enabled in overrides ; they can only narrow tools, the directory must be inside an allowed root also after resolving symlinks , and the system prompt is only appended. Never applicable to bridge/ models. - system messages . With replace the CLI system prompt is replaced by the request's messages the agent's system prompt stays first ; the permissions of the agent's tools do not change. - bypassPermissions is rejected unless allow bypass permissions: true , in which case a warning is printed at startup for every affected agent. - Logs. At info level and above, prompts and answers are never logged; at debug they are truncated to 500 characters. sk-ant-… keys and the bridge key are replaced with REDACTED in logs and errors. - Processes. Every turn is a separate process, started without a shell, with the prompt on stdin. Timeouts, client disconnection or server shutdown terminate the whole process tree process group on Unix, taskkill /T on Windows . Client examples: - Go with the official SDK: examples/go https://github.com/R3n3r0/agent-bridge/blob/main/examples/go/main.go - Python with the official SDK: examples/python/client.py https://github.com/R3n3r0/agent-bridge/blob/main/examples/python/client.py - Python, function calling: examples/python/tools.py https://github.com/R3n3r0/agent-bridge/blob/main/examples/python/tools.py - Python, images: examples/python/images.py https://github.com/R3n3r0/agent-bridge/blob/main/examples/python/images.py - curl: examples/curl.sh https://github.com/R3n3r0/agent-bridge/blob/main/examples/curl.sh Endpoints: | Method and path | Purpose | |---|---| | POST /v1/chat/completions | Runs a turn JSON or SSE | | GET /v1/models , GET /v1/models/{id} | Lists configured agents and bridge/ aliases bridge/<model name names answer the detail endpoint but are not listed ; the prefix follows builtin prefix | | GET /stats | Per-agent statistics; ?reset=true resets them after returning them | | GET /metrics | Prometheus metrics with metrics: true | | GET /healthz , GET /readyz | Liveness and readiness | Request headers: | Header | Effect | |---|---| | X-Session-Id , X-Session-Reset | Session to resume or restart | | X-Agent-Bridge-Tool-Mode | stateful or stateless for client functions | | X-Agent-Bridge-System-Mode | prompt , append or replace for system messages | | X-Agent-Cwd , X-Agent-Allowed-Tools , X-Agent-System-Prompt | Overrides, only if enabled | | X-Request-Id | Identifier reported in logs and in the response | Response headers: X-Session-Id , X-Request-Id and, in non-stream responses, X-Agent-Bridge-Turns , X-Agent-Bridge-Cost-USD , X-Agent-Bridge-Duration-Ms . Admin page with admin: true or AGENT BRIDGE ADMIN=1 : GET /admin and /admin/api/logins to log in to the CLIs docs/docker.md https://github.com/R3n3r0/agent-bridge/blob/main/docs/docker.md . Commands: agent-bridge serve default , check-config , doctor -live , version ; mcp-tools is internal, started by the CLI for client functions. doctor checks the CLI and its version, the consistency of the authentication mode and directory permissions; with -live it runs a test turn on Haiku with the Codex and Kimi backends: the model configured in the CLI, and for Codex codex login status . - temperature , top p , seed , logprobs , presence penalty , frequency penalty and logit bias are accepted and ignored; stop , n and max tokens are emulated or partial see Generation parameters generation-parameters . - Function calling: a binding tool choice , parallel tool calls: false and function schemas are instructions to the model, not enforced constraints. - Content parts other than text and image url audio, files return 400 unsupported content ; detail on images is accepted and ignored. - No support for /v1/responses , /v1/embeddings , image generation, audio, or other providers. - Prompts up to 9 MB the CLI limits stdin to 10 MB . - When streaming, the X-Agent-Bridge-Turns , -Cost-USD and -Duration-Ms response headers are not available headers are sent before execution ; cost and tokens are in the logs, in /stats and in the usage chunk when requested with stream options.include usage . - When streaming, progress is sent as single-line SSE comments without a following blank line, because some SDKs treat a blank line after a comment as an empty event. - A turn can take minutes: the model may work through several steps before answering. - The exact values of the apiKeySource field of the init event are not documented: the server treats only none as "no API key". Does it support tools? Yes, of two kinds: client functions through OpenAI function calling, and agent tools on the server files, commands, search, MCP servers for configured agents. See Two ways to use it two-ways-to-use-it . Why don't temperature and top p work? The bridge drives the Claude Code CLI, which has no option for them, and calling the model API directly would bypass the CLI and, with a subscription, its terms . What the CLI does offer is mapped: see Generation parameters generation-parameters . Does it accept images? Yes, image url parts with data: or http s URLs, as in the OpenAI API. See Images images . Do I need to change my OpenAI client? No: change base url http://127.0.0.1:8787/v1 , api key the AGENT BRIDGE API KEY , or any value if it is not set and model . Do I need a configuration file for every agent? No, if agents are defined in the client: instructions in system , tools in tools , a bridge/ model. The file is only needed for agents that use the server's tools. Is the context duplicated if I send the whole history? Without X-Session-Id every request starts again from the full history, like a stateless API. With X-Session-Id the session is resumed and the CLI receives only the new messages. What happens if I change working directory mid-conversation? CLI sessions are tied to the project directory: the server starts a new one. Can I expose the server on the network? Only explicitly allow remote plus AGENT BRIDGE API KEY , behind TLS, and in subscription mode only for the account holder. For several users use api mode. Two requests on the same session? They are serialized on busy: wait or the second gets 409 on busy: reject . Layered structure with interfaces and replaceable implementations: docs/architecture.md https://github.com/R3n3r0/agent-bridge/blob/main/docs/architecture.md . Full technical specification, revision 1.4: docs/specification.md https://github.com/R3n3r0/agent-bridge/blob/main/docs/specification.md . go test -race ./... uses a fake CLI binary, no credentials ./scripts/coverage.sh minimum coverage of the main packages CI never uses the real CLI or credentials. Manual checks before every release are in docs/release-checklist.md https://github.com/R3n3r0/agent-bridge/blob/main/docs/release-checklist.md . agent-bridge is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or at your option any later version. See LICENSE https://github.com/R3n3r0/agent-bridge/blob/main/LICENSE . The license covers this project's code only. Claude Code is a separate product with its own terms, installed and used by you under your agreement with Anthropic.