Install Prompt Royale

1. Add it to your agent

Claude Code

/plugin marketplace add ionamol/prompt-royale
/plugin install prompt-royale@prompt-royale

Codex

[mcp_servers.prompt-royale]
command = "npx"
args = ["-y", "@unwantedbits/prompt-royale"]
tool_timeout_sec = 120

OpenCode

{
  "mcp": {
    "prompt-royale": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@unwantedbits/prompt-royale"
      ],
      "enabled": true
    }
  }
}

Cline and other MCP clients

{
  "mcpServers": {
    "prompt-royale": {
      "command": "npx",
      "args": [
        "-y",
        "@unwantedbits/prompt-royale"
      ]
    }
  }
}

2. Ask for a battle

Battle free models on a one-page landing for a coffee roaster.

If your agent says no free models were found, it can connect OpenRouter for you: approve once in the browser and try again.

• OpenRouterFree models after one browser sign-in: ask your agent to connect OpenRouter (royale_connect).
• Ollama and LM StudioUsed automatically while they are running.
• PollinationsA free image model with no key, for image battles.
• freellmapiOptional: if you run it on port 3001, its free catalog joins too.
• Claude CodeCode battles only, when you name it (claude:default). It runs sandboxed and can only write its page.

Contestants never read your files: models only receive the prompt, and Claude Code runs restricted to writing its own page in an empty folder.

Tools

• royale_checkShows the contestants found on your machine and your login.
• royale_connectConnects free OpenRouter models in the browser.
• royale_battleRuns one prompt against several models. Returns labels only.
• royale_reviewOpens the blind king-of-the-hill vote in your browser.
• royale_resultShows progress, then the models once you decide to publish or keep it private.
• royale_applyCopies the winner into your project.
• royale_loginConnects your agent to your Prompt Royale account.
• royale_publishPreviews, then publishes a voted battle.
• royale_rematchRuns a public battle's prompt against your own free models.

Optional: your own API keys

To add paid models, list them in ~/.prompt-royale/config.json. The file names the environment variable that holds each key, never the key itself. Paid models only compete when you name them in a battle.

{
  "contestants": [
    { "id": "openai", "type": "byok", "baseUrl": "https://api.openai.com/v1", "apiKeyEnv": "OPENAI_API_KEY", "models": ["gpt-image-1"] },
    { "id": "anthropic", "type": "byok", "baseUrl": "https://api.anthropic.com/v1", "apiKeyEnv": "ANTHROPIC_API_KEY", "models": ["claude-opus-5"] }
  ],
  "defaults": { "count": 4, "timeoutMs": 600000 }
}

Agents without skills

Add these rules to your AGENTS.md so any agent uses the tools safely.

## Prompt Royale
- Use prompt-royale tools when asked to compare models or battle a prompt.
- Write a self-contained prompt. Never include project code, file contents, env values or secrets.
- Run royale_battle; if it says running, check royale_result until it is ready. Then royale_review and ask the user to vote.
- After the vote, ask the user to publish (royale_publish preview, then confirm with its confirmToken) or keep it private (royale_result with keepPrivate: true). Models are revealed only after that choice.
- Never guess which model made which label before royale_result reveals it.