Duel Agents

Use, extend, and ship with Duel Agents: the IDE-native routing layer that runs prompts against multiple models and picks the cheapest answer that still wins.

This repo is the official integration package for duelagents.com.

Requirements

Every tool in this repo routes LLM traffic through https://duelagents.com/v1 with a Duel API key (duel_<prefix>_<secret>).

You cannot use raw Anthropic or OpenAI keys with these integrations. Get a key from the dashboard:

https://duelagents.com/dashboard/settings (subscribe → create API key)

Quick start

# 1. Get your key from the dashboard, then:
export DUEL_API_KEY=duel_yourprefix_yoursecret

# 2. Install for your tools
npx @duel-agents/install all

# 3. Verify
npx @duel-agents/install doctor

Install per tool

| Tool | Command | |------|---------| | Claude Code | npx @duel-agents/install claude-code | | Cursor | npx @duel-agents/install cursor | | Codex CLI | npx @duel-agents/install codex | | OpenClaw | npx @duel-agents/install openclaw | | All | npx @duel-agents/install all |

Claude Code plugin

git clone https://github.com/2aronS/Duel-Agents.git
cd duel-agents
claude plugin install ./integrations/claude-plugin
npx @duel-agents/install claude-code

Use /duel-agents:setup in Claude Code for guided setup.

Cursor

The installer copies a skill to .cursor/skills/duel-agents/ and writes DUEL_API_KEY to your project .env.

You still need to set Settings → Models → Override OpenAI Base URL to https://duelagents.com/v1 with your Duel key. See templates/cursor-models.override.md.

Codex CLI

Writes OPENAI_BASE_URL and OPENAI_API_KEY (your Duel key) to .env. Restart Codex after install.

OpenClaw

Patches ~/.openclaw/openclaw.json with a duel provider and sets default model to duel/duel-auto. Telegram/Discord channels are unchanged. Only the model backend switches to Duel.

npx @duel-agents/install openclaw
openclaw config validate

Reference config: templates/openclaw.duel.json5

Build on top

Use @duel-agents/sdk in your apps, agents, and scripts. apiKey is required.

npm install @duel-agents/sdk

import { DuelClient } from "@duel-agents/sdk";

const duel = new DuelClient({
  apiKey: process.env.DUEL_API_KEY!, // required (from dashboard)
});

// OpenAI-compatible
const chat = await duel.chat.completions.create({
  model: "duel-auto",
  messages: [{ role: "user", content: "Explain concurrent agents briefly." }],
});

// Anthropic-compatible
const msg = await duel.messages.create({
  model: "duel-auto",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello" }],
});

Hermes Agent, Venice, and any OpenAI-compatible client can use the same pattern:

OPENAI_BASE_URL=https://duelagents.com/v1
OPENAI_API_KEY=duel_yourprefix_yoursecret

Configuration

| Variable | Purpose | |----------|---------| | DUEL_API_KEY | Your Duel API key (required) | | DUEL_AGENTS_API_KEY | Alias accepted by the installer | | DUEL_PROXY_URL | Override proxy URL (staging only) | | OPENCLAW_CONFIG_PATH | Custom OpenClaw config path |

Troubleshooting

| Symptom | Fix | |---------|-----| | Invalid API key format | Key must be duel_ + 8 chars + _ + 32 chars. Create one at the dashboard. | | 401 from doctor | Key revoked or subscription inactive. Create a new key on billing/settings. | | Could not reach Duel API | The proxy at duelagents.com/v1 must be running. Key format can still be valid; retry later. | | OpenClaw won't start | Run openclaw config validate after install; restore from openclaw.json.bak if needed. | | Cursor still uses OpenAI | Confirm model override URL and that the API key field is your duel_* key. | | Skill copy failed after npm install | Re-run npm run build in the repo, or reinstall @duel-agents/install. Skills ship inside the package. |

Repo map

packages/core     @duel-agents/core    validation, env maps, connectivity
packages/cli      @duel-agents/install installer CLI
packages/sdk      @duel-agents/sdk     TypeScript API client
integrations/     Claude plugin, Cursor skill, OpenClaw skill
templates/        Example env and config files

Development

npm install
npm run build
npm test

See CONTRIBUTING.md.

License

MIT. See LICENSE.