roadmodel

# 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 six-field block — `MODEL / PLATFORM / MAX MODE / THINKING / CONVERSATION / RATIONALE` — 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. [](https://pypi.org/project/roadmodel/) [](https://pypi.org/project/roadmodel/) [](LICENSE) [](https://github.com/nathanramoscfa/roadmodel/actions/workflows/tests.yml) [](https://github.com/nathanramoscfa/roadmodel/actions/workflows/phase-verify.yml) ## Install ```sh pip install roadmodel ``` Python 3.11 or newer. ## 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](docs/mcp-setup.md); tool signatures and return schemas are documented in [docs/mcp-tools.md](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: ```sh 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: ```sh 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](docs/byo-key-setup.md) for the full guide. ```sh 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](docs/user-context-setup.md). ```sh 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 six-field block: ```sh roadmodel recommend "Refactor auth middleware across 12 files" ``` ``` MODEL: claude-opus-4-7 PLATFORM: Claude Code MAX MODE: On THINKING: High CONVERSATION: New RATIONALE: Coding PRIMARY with cross-file scope and High complexity. Opus 4.7 is S-tier on coding-agent benchmarks and the only model in the catalog rated S for long-context recall. PLATFORM Claude Code is funded by claude.ai Max ($0 marginal); THINKING High per the selection-algorithm rule for High-complexity coding. ``` 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: | Provider | Env var | | --------- | ------------------- | | Anthropic | `ANTHROPIC_API_KEY` | | OpenAI | `OPENAI_API_KEY` | | Google | `GOOGLE_API_KEY` | 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](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 budget posture so the `<access-selection>` step can pick a **platform** and **thinking level** 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](docs/user-context-setup.md). ## Subcommands | Command | What it does | | -------------------------------- | ---------------------------------------------------------------------------------- | | `roadmodel recommend PROMPT` | Recommend a six-field block for the given prompt. | | `roadmodel recommend --file P` | Same, but read the prompt text from file `P`. | | `roadmodel recommend --json` | Emit the parsed six fields as JSON instead of the labeled text block. | | `roadmodel recommend --provider` | Override which provider answers (`anthropic` / `openai` / `google`). | | `roadmodel recommend --model` | Override the specific model ID on the chosen provider. | | `roadmodel recommend --user-context PATH` | Override the user-context.md location for this invocation. | | `roadmodel catalog show` | Print the bundled `model-selector.txt` (use `--doc tier-cost-scale` for the price doc). | | `roadmodel catalog path` | Print the on-disk path of the bundled catalog document (same `--doc` flag). | | `roadmodel context show` | Print the resolved `user-context.md` file. | | `roadmodel context path` | Print the resolved `user-context.md` path (or the bootstrap target if missing). | | `roadmodel context init` | Bootstrap `user-context.md` from the bundled template (`--force` to overwrite). | | `roadmodel version` | Print the installed version. | ## How it works The CLI ships three documents as package data: [`model-selector.txt`](docs/model-selector.txt) (the selection algorithm and the per-model access-methods catalog), [`model-tier-cost-scale.md`](docs/model-tier-cost-scale.md) (per-token prices and tier ratings), and [`user-context.example.md`](docs/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 / PLATFORM / MAX MODE / THINKING / CONVERSATION / RATIONALE` block 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 `THINKING` are filled by the `<access-selection>` step, which depends on the subscriptions and API-key state declared in your `user-context.md`. ## 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**](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](ROADMAP.md) for the phase plan and shipping order. ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) for branch naming, pull request scope, the catalog-edit process, and the [Code of Conduct](CODE_OF_CONDUCT.md) that applies in community spaces. Report security issues privately per [SECURITY.md](SECURITY.md). ## License Licensed under the [Apache License, Version 2.0](LICENSE). Bundled third-party attributions are listed in [NOTICE](NOTICE).