recompose is a free, open-source desktop app that composes your AI subscriptions, API keys, aggregators, and local runtimes into gateways served from your own machine. You define virtual models, wire them to real providers on a node canvas, and point clients such as Claude Code, Codex, and Cursor at one local address.
Download
brew install --cask recomposesh/tap/recompose
The app updates itself through whichever channel installed it. A macOS copy in the Applications folder pulls updates on its own, and a Homebrew install counts: brew upgrade leaves it alone. The AppImage replaces itself, and a deb install waits for apt. macOS builds carry a Developer ID signature and Apple's notary ticket, and need macOS 12 Monterey or later.
[!NOTE]
The Windows installer carries no signature yet, so SmartScreen shows a warning on first launch. Pick "More info," then "Run anyway." Until signing lands, a Windows install also updates by downloading the new installer rather than through the app.
How it works
A gateway is a running local server that owns one port. Its canvas wires virtual models through routers to provider targets:
Claude Code ──▶ http://127.0.0.1:8397
│
[ gateway "coding" ]
│
[ virtual model "fast" ]
│
[ router · failover ]
#1 │ #2 │
[ Claude · sonnet ] [ OpenAI · gpt-5 ]
Claude Code points at the gateway through an environment variable in front of the command:
ANTHROPIC_BASE_URL="http://127.0.0.1:8397" claude
Every gateway carries a connect sheet that writes the exact setup for each client it knows. The sheet covers terminal agents such as Codex CLI and opencode, editors such as Cursor and Cline, desktop apps, and a plain curl for everything else.
Features
- One address for every client: each gateway serves five API dialects on its own port: Anthropic Messages (
/v1/messages), OpenAI Chat Completions (/v1/chat/completions), OpenAI Responses (/v1/responses), Gemini (/v1beta/models), and Gemini Interactions (/v1/interactions). The request path picks the dialect, and there is nothing to configure per client.
- Virtual models: clients see aliases such as
fast or smart. Swap the real model behind that name without touching a single client config.
- Composable routing: a failover router sends traffic to the topmost healthy target, a round-robin router spreads it evenly, and a conditional router asks a judge model to read each request and pick the branch whose rule it matches. Routers nest to combine strategies.
- Judge-routed branches: describe each branch in plain words, such as "asks to write or change code," and bind a fast, cheap judge. Anything the judge can't place lands on the else branch, a conversation keeps the branch it first earned, and routing trouble never drops a request.
- Every provider shape: subscription plans such as Claude, ChatGPT, and GitHub Copilot, API keys the gateway spends request by request, aggregators such as OpenRouter and Groq, and the local runtimes Ollama, LM Studio, llama.cpp, and vLLM, plus any server of your own.
- Private by default: no signup, no telemetry. Credentials stay on your machine in
~/.recompose, with secrets sealed through the system keychain where the platform provides one. Gateways answer this machine alone until you widen the bind address in settings, and each gateway can require its own API key.
Documentation
The handbook lives at recompose.sh/docs: installation, connecting providers, composing gateways, and operating them day to day.
Building from source
Requires Node 22.18 or later and pnpm 11.
pnpm install
pnpm dev
pnpm dev opens the Electron app with hot reload and serves the site beside it. pnpm build compiles every workspace, and pnpm test runs the unit suites.
Architecture
apps/desktop: the Electron app. The main process owns the gateway engine in a utility process, and the renderer is a React app organized by Feature-Sliced Design.apps/web: the public site: landing, docs, download, and changelog.packages/engine: the gateway server itself: dialect translation, routing, and serving.packages/contracts: the schemas the desktop app and the engine share.docs/adr: every technical decision, recorded as an Architecture Decision Record (ADR).
