Duel-Agents: A Proxy Router That Picks the Cheapest Winning Model
CLI, SDK, and IDE plugins for Duel Agents
At a glance
- What is it?
- Duel-Agents is an MIT-licensed integration package that points Claude Code, Cursor, Codex CLI, OpenClaw, LangChain and LlamaIndex at a single hosted proxy, duelagents.com/v1, and lets that proxy choose among models. The SDK is the easy part. The hard constraint is that raw Anthropic and OpenAI keys do not work here.
- Who is it for?
- Adopt Duel-Agents if you already have a Duel subscription and want one key covering Claude Code, Cursor, Codex CLI, OpenClaw and the Python frameworks, because the installer writes the base URL and key into each tool's config for you. Do not adopt it if you need to keep using your own Anthropic or OpenAI keys, since the README states plainly that these integrations will not accept them, or if your traffic cannot leave your own infrastructure.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 78 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem Duel-Agents solves is key sprawl across coding tools
A developer running Claude Code, Cursor and Codex CLI normally holds three separate credentials and three separate billing relationships, and each tool picks its own model with no shared notion of cost. Duel-Agents collapses that into one credential. Every tool in the repository routes LLM traffic through https://duelagents.com/v1 using a single Duel API key in the form duel_<prefix>_<secret>, and the routing decision is made on the server side by a model named duel-auto. The README describes the layer as running prompts against multiple models and picking the cheapest answer that still wins. The audience is therefore narrow and specific: developers who already pay for Duel and want their editor and terminal agents to share one endpoint, plus teams building agents on top of the SDK who want that routing without writing their own multi-model fan-out. It is not a local router. The selection logic is not in this repository, and the repository does not document how a winner is determined.
What actually sits in the repository
The repo map lists four TypeScript packages and one Python directory. packages/core holds validation, environment variable maps and connectivity checks. packages/cli is the installer, published as @duel-agents/install. packages/sdk is the TypeScript client, @duel-agents/sdk. integrations/ contains a Claude plugin, a Cursor skill and an OpenClaw skill. python/ contains langchain-duel and llama-index-llms-duel. templates/ holds example env and config files, including env.cursor.example, env.codex.example, env.openclaw.example, openclaw.duel.json5 and cursor-models.override.md. The split matters when you debug: a failed install is a CLI problem, a failed call from your own code is an SDK problem, and a failed call from your editor is usually a config file the installer wrote. The CLI is the only component that touches other tools' configuration. The SDK never does.
How the installer rewires each tool
The mechanism is config rewriting, and it differs per target. For Claude Code, the README shows cloning the repository, running claude plugin install ./integrations/claude-plugin, then npx @duel-agents/install claude-code, with a guided /duel-agents:setup command inside Claude Code. For Cursor, the installer copies a skill into .cursor/skills/duel-agents/ and writes DUEL_API_KEY into the project .env, but it does not finish the job: the README states you still have to set Settings, Models, Override OpenAI Base URL to https://duelagents.com/v1 with your Duel key, and points at templates/cursor-models.override.md. That manual step is the most likely place for a half-configured install to sit unnoticed. For Codex CLI, the installer writes OPENAI_BASE_URL and OPENAI_API_KEY (your Duel key) into .env, and Codex must be restarted afterwards. For OpenClaw, it patches ~/.openclaw/openclaw.json with a duel provider and sets the default model to duel/duel-auto, leaving Telegram and Discord channels untouched. Only the model backend switches. OpenClaw is the one target where the installer edits a file outside your project directory, which is why the README pairs the install with openclaw config validate and documents restoring from openclaw.json.bak.
Install commands and the environment variables that matter
The quick start is three commands: export DUEL_API_KEY=duel_yourprefix_yoursecret, then npx @duel-agents/install all, then npx @duel-agents/install doctor. Per-tool variants are npx @duel-agents/install claude-code, cursor, codex, openclaw, or all. The configuration table lists four variables. DUEL_API_KEY is required. DUEL_AGENTS_API_KEY is an alias the installer also accepts. DUEL_PROXY_URL overrides the proxy URL, and the README marks it staging only, so treating it as a production knob is a misuse. OPENCLAW_CONFIG_PATH sets a custom OpenClaw config path, and there is a constraint attached: the path must live under ~/.openclaw, otherwise the installer refuses with OPENCLAW_CONFIG_PATH must be inside. On the SDK side, apiKey is required in the DuelClient constructor, and the client exposes both an OpenAI-shaped surface (duel.chat.completions.create) and an Anthropic-shaped one (duel.messages.create), both taking model: "duel-auto". The Python packages follow the same pattern: ChatDuel(model="duel-auto") and DuelLLM(model="duel-auto") read DUEL_API_KEY from the environment. If you would rather not install them, any OpenAI-compatible client works by pointing base_url at https://duelagents.com/v1.
The proxy is a hard dependency, and the failure modes follow from it
The README is unusually direct about this: you cannot use raw Anthropic or OpenAI keys with these integrations. That single sentence rules out a set of use cases. If your organisation has an existing Anthropic contract, or if prompts must not leave infrastructure you control, Duel-Agents is the wrong tool regardless of how clean the installer is. The troubleshooting table maps the dependency to concrete symptoms. A 401 from doctor means the key was revoked or the subscription is inactive, not that the key is malformed. Could not reach Duel API means the proxy must be running, and the README notes the key format can still be valid, which means a connectivity failure and a credential failure look different and should be diagnosed differently. Invalid API key format is a client-side check: the key must be duel_ plus 8 characters plus underscore plus 32 characters. The remaining entries are local. Cursor still using OpenAI means the model override URL or the key field is wrong. A skill copy failure after npm install is fixed by re-running npm run build in the repo or reinstalling @duel-agents/install, because skills ship inside the package. Nothing in the material describes retries, timeouts or fallback behaviour when the proxy is degraded, so that is an open question rather than a documented guarantee.
What the SDK does not do
The SDK is a client, not a router. It sends your request to the proxy and returns the response; the selection among models happens behind the endpoint, and the repository does not expose a way to inspect or override the choice beyond the model string. There is no documented local scoring, no cost report, and no API for reading which model answered a given call. If your reason for considering Duel-Agents is auditability of model selection, the material does not support that expectation. The two compatibility surfaces are the compensating feature: because the proxy is OpenAI wire compatible, the same endpoint serves LangChain, LlamaIndex, Hermes Agent, Venice and any other OpenAI-compatible client through OPENAI_BASE_URL and OPENAI_API_KEY, which means you can adopt it without rewriting application code. That is a real advantage, but it is a compatibility advantage, not a routing one.
Alternatives and where the approaches diverge
The obvious comparison is LiteLLM, a self-hosted proxy that also presents an OpenAI-compatible endpoint in front of many providers. The difference is where the decision lives. With LiteLLM you run the process, hold the provider keys, and write the routing rules yourself, so cost and model selection are yours to define and your prompts stay on your infrastructure. Duel-Agents inverts that: you hold one Duel key, the selection is a hosted service, and the value you get is the installer that configures Claude Code, Cursor, Codex CLI and OpenClaw for you. LiteLLM gives you no installer for those tools; Duel-Agents gives you no way to run the router yourself. A second, narrower comparison is the direct Anthropic or OpenAI key per tool, which the README explicitly excludes here but which remains the baseline: zero extra hops, zero extra subscription, and no shared routing. Choose between them on one question. Do you want to own the routing logic and the keys, or do you want one credential and a config writer?
Maintenance, versioning and licence
The project is at v0.1.0, released 2026-05-28, with the last push to main on 2026-06-29. That is a pre-1.0 package, and the repository layout suggests why upgrades deserve attention: the installer writes into other tools' configuration, including a file outside your project at ~/.openclaw/openclaw.json, so an upgrade can change configuration you did not author. The OpenClaw backup file, openclaw.json.bak, and the openclaw config validate command are the documented recovery path, and they are worth running after every install rather than only when something breaks. The licence is MIT, which permits commercial use and modification, but the MIT grant covers this integration code, not the hosted proxy, the subscription, or the model providers behind it. Nothing in the material states terms for the service itself. Treat the licence as covering the packages in this repository only, and read the service terms separately. This is a description of what the licence text does, not legal advice.
Editorial conclusion
Adopt Duel-Agents if you already have a Duel subscription and want one key covering Claude Code, Cursor, Codex CLI, OpenClaw and the Python frameworks, because the installer writes the base URL and key into each tool's config for you. Do not adopt it if you need to keep using your own Anthropic or OpenAI keys, since the README states plainly that these integrations will not accept them, or if your traffic cannot leave your own infrastructure. Before installing, verify three things: that the key you generate matches the duel_ + 8 characters + _ + 32 characters format, that https://duelagents.com/v1 responds from your network, and that you have a copy of ~/.openclaw/openclaw.json, because the OpenClaw installer patches it in place and the backup file is the documented way back.
Community notes