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.

Star History

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

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 and templates/env.cursor.example.

Codex CLI

Writes OPENAI_BASE_URL and OPENAI_API_KEY (your Duel key) to .env. Restart Codex after install. See templates/env.codex.example.

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 and templates/env.openclaw.example

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

LangChain and LlamaIndex

Duel is OpenAI wire compatible, so it works with the major Python frameworks.

Official packages

pip install langchain-duel        # LangChain
pip install llama-index-llms-duel # LlamaIndex

from langchain_duel import ChatDuel

llm = ChatDuel(model="duel-auto")  # reads DUEL_API_KEY
llm.invoke("Explain concurrent agents in one sentence.")

from llama_index.llms.duel import DuelLLM

llm = DuelLLM(model="duel-auto")   # reads DUEL_API_KEY
llm.complete("Explain concurrent agents in one sentence.")

Source for both lives in python/. They default to duel-auto routing and the https://duelagents.com/v1 proxy.

Without the packages

Any LangChain or LlamaIndex OpenAI client works by pointing at the proxy:

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="duel-auto",
    base_url="https://duelagents.com/v1",
    api_key="duel_yourprefix_yoursecret",
)

Configuration

Troubleshooting

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
python/           langchain-duel, llama-index-llms-duel
templates/        Example env and config files

Development

npm install
npm run build
npm test

See CONTRIBUTING.md.

License

MIT. See LICENSE.