roadmodel

A BYO-key command-line tool that recommends which AI model on which platform with which settings for a given prompt. Point it at a task description, and it returns a labeled block — MODEL / BACKUP / PLATFORM / CONVERSATION / RATIONALE, plus the setting fields the chosen platform actually exposes — grounded in a bundled benchmark and pricing catalog (Cursor pricing, Artificial Analysis, LiveCodeBench, τ²-bench, SWE-bench, MMMU, LMArena) and filtered against your own subscriptions and API keys. Built for developers who use several AI subscriptions (Claude Code, Cursor, Codex / ChatGPT, raw provider APIs) and want a deterministic answer to "what should I use for this?" instead of guessing.

Install

pip install roadmodel

Python 3.11 or newer.

Updating to the latest models

roadmodel's benchmark and pricing catalog is bundled inside the installed wheel — the CLI, MCP server, and planning kit all read that offline copy, and they only know about the models that shipped with the version you have. New models, price changes, and availability edits land in the catalog upstream (a daily job keeps it current) and reach you when a new release ships them. To pull the latest catalog, upgrade the package:

pip install -U roadmodel

That single command covers every usage mode — do it at the start of each planning phase, or whenever a model you care about has changed:

• CLI — upgrade and the next roadmodel recommend uses the fresh catalog. Confirm what you have with roadmodel version and inspect the bundled catalog with roadmodel catalog show.
• MCP server — upgrade in the same environment where roadmodel-mcp is installed (pip install -U "roadmodel[mcp]"), then restart your MCP client (Cursor / Claude Code / Claude Desktop) so it reloads the server. If you registered the server once at user scope via roadmodel setup-mcp, upgrading that one environment updates every project.
• Planning kit — the exported kit is a snapshot of the catalog at export time, so upgrade then re-run roadmodel export-kit to refresh it. The shell alternative (scripts/export-planning-kit.sh) instead fetches the catalog fresh from this repo's main branch on every run, so it always writes the newest catalog without a pip upgrade.

See CHANGELOG.md for what each release changed.

MCP server

Install the MCP runtime with pip install "roadmodel[mcp]" to enable the roadmodel-mcp stdio server entrypoint; plain pip install roadmodel keeps the SDK optional and does not install mcp. The server exposes three tools — recommend_model, generate_phase_roadmap, and read_catalog — to any MCP-compatible client (Cursor, Claude Code, Claude Desktop, VS Code + Continue). Per-client registration walk-throughs live in docs/mcp-setup.md; tool signatures and return schemas are documented in docs/mcp-tools.md.

Planning kit ($0 marginal recommendations)

To author project/phase roadmaps with per-step model recommendations in another project, export the planning kit into it and let the AI already open in your editor (e.g. Claude Code on a flat plan) run the selector in its own context — no per-call API spend, just the editor session you already pay for.

Cross-platform (recommended). With roadmodel installed, one command writes the kit on Windows, macOS, or Linux — no shell or network needed:

cd /path/to/other-project
roadmodel export-kit            # writes ./planning with selector + cost-scale
                                # + templates + HOW-TO-USE + your user-context

It uses the catalog bundled in the installed wheel, so refresh with pip install -U roadmodel and re-run roadmodel export-kit at the start of each phase. Flags: --dest <subdir>, --force (overwrite an existing kit user-context.md), --user-context <path>.

Shell alternative (no install). A bash script fetches the kit fresh from this repo's main branch instead of from an installed wheel:

scripts/export-planning-kit.sh /path/to/other-project

Flags: --dest <subdir>, --ref <git-ref>, --local (copy from a local checkout instead of GitHub), --user-context <path>. On Windows PowerShell, call curl.exe (not the curl alias) if you fetch files by hand; the export-kit command above avoids that entirely.

Either way the in-editor AI runs the algorithm itself rather than calling the recommender service. Use the MCP server above instead when you want deterministic, structured recommendations in a script or CI.

Quickstart

Three steps from a fresh install to a parsed recommendation block.

1. Export an API key for any one of the three providers. Anthropic shown here; OpenAI and Google work the same way — see docs/byo-key-setup.md for the full guide.

export ANTHROPIC_API_KEY=sk-ant-...

2. Run roadmodel recommend once to bootstrap your user-context file. On the first invocation, the CLI writes a copy of the bundled template to ~/.config/roadmodel/user-context.md (or $XDG_CONFIG_HOME/roadmodel/user-context.md when XDG_CONFIG_HOME is set), prints a one-line stderr notice telling you what it did, and exits without calling the provider. Open the file and replace the $XXX and Yes/No placeholders with your actual subscription amounts and API-key state. The full field-by-field walk-through lives in docs/user-context-setup.md.

roadmodel recommend "Refactor auth middleware across 12 files"
# stderr: Created /home/you/.config/roadmodel/user-context.md from
#         bundled template. Edit it with your real subscription
#         state, then re-run.

$EDITOR ~/.config/roadmodel/user-context.md

3. Re-run. With the user-context filled in, the same command calls your chosen provider and prints a parsed recommendation block:

roadmodel recommend "Refactor auth middleware across 12 files"

MODEL: claude-opus-4-7
BACKUP: claude-sonnet-5
PLATFORM: Claude Code
EFFORT: High
THINKING: On
CONVERSATION: New
RATIONALE: TASK: Cross-file coding refactor spanning twelve modules.
PICK: Opus 4.7 is S-tier on coding-agent benchmarks and the only
model in the catalog rated S for long-context recall.
EFFORT: High effort with extended thinking on matches the
multi-file blast radius without over-buying the ceiling.

The setting fields are platform-conditional: a block carries only the dials the chosen platform actually has. Claude Code exposes an effort dial and a thinking toggle, so the example emits EFFORT and THINKING and no MAX MODE line at all — Claude Code has no Max Mode control, and a dial a surface lacks is omitted rather than reported as Off. Cursor is the inverse: it emits MAX MODE and no EFFORT / THINKING. MODEL, BACKUP, PLATFORM, CONVERSATION, and RATIONALE are always present.

Pass --json to emit the same fields as machine-readable JSON, or --file PATH to read the prompt from disk.

BYO-key setup

roadmodel ships with no provider key built in — it calls your Anthropic / OpenAI / Google account on every recommendation and charges your account. Set any one of the three environment variables and the CLI auto-selects that provider:

The full guide — generating keys in each provider's console, storing them in a shell profile or ~/.config/roadmodel/config.toml, precedence rules, and verifying with a smoke call — is docs/byo-key-setup.md.

User context setup

roadmodel reads a per-user Markdown file describing your active subscriptions, API keys, platform preference order (and optional platform allow/deny list), and budget posture so the <access-selection> step can pick a platform and the settings that platform exposes alongside the model. The resolved default path is ~/.config/roadmodel/user-context.md (or $XDG_CONFIG_HOME/roadmodel/user-context.md when XDG_CONFIG_HOME is set); override it for a single run with --user-context PATH or for a whole shell with ROADMODEL_USER_CONTEXT=PATH. The full walk-through — first-run bootstrap, full precedence chain, field-by-field schema, when to update — is docs/user-context-setup.md.

Subcommands

How it works

The CLI ships three documents as package data: model-selector.txt (the selection algorithm and the per-model access-methods catalog), model-tier-cost-scale.md (per-token prices and tier ratings), and user-context.example.md (the user-state template). At recommendation time, roadmodel recommend reads your filled-in user-context.md from disk, concatenates the three docs into a single system prompt, and calls the provider you configured. The provider returns a MODEL / BACKUP / PLATFORM / CONVERSATION / RATIONALE block — plus the setting fields the chosen platform exposes — following the <output-format> specification inside model-selector.txt. MODEL is chosen by <selection-algorithm> against your prompt's task category and complexity; PLATFORM and the settings that come with it are filled by the <access-selection> step, which depends on the subscriptions and API-key state declared in your user-context.md. Because the platform decides which dials exist, the field set varies per block: an effort/thinking surface emits EFFORT + THINKING, Cursor emits MAX MODE, and a dial the surface does not have is left out entirely instead of being reported as Off or N/A.

Benchmarks & ratings

Each model carries a per-category capability rating on an S → D scale, and the recommender grounds its rationale in public benchmarks (SWE-bench Verified, τ²-bench, Terminal-Bench, Humanity's Last Exam, and more). See docs/benchmarks-and-ratings.md for what the scale means and a linked index of every benchmark the recommender cites — in the web app, each benchmark term in a recommendation's rationale links straight to its source.

Project status

roadmodel is in Phase 1 — the open-source CLI release. Phase 2 adds an MCP server alongside the CLI; later phases add a hosted SaaS at roadmodel.ai. The project was previously named model-selector and was renamed to roadmodel ahead of the public release; the canonical bundled-doc filename model-selector.txt is preserved so existing references in other projects keep working. Until v1.0.0, expect breaking changes to the CLI surface as Phase 2 lands.

See ROADMAP.md for the phase plan and shipping order.

Contributing

See CONTRIBUTING.md for branch naming, pull request scope, the catalog-edit process, and the Code of Conduct that applies in community spaces. Report security issues privately per SECURITY.md.

License

Licensed under the Apache License, Version 2.0. Bundled third-party attributions are listed in NOTICE.