Somm

A model advisor for your AI agents. Fetches the models you actually have access to from OpenCode subscriptions and OpenRouter, cross-references benchmarks and pricing, and recommends the best model for each agent role — with the reasoning.

It's an MCP server, so it plugs into whatever agent host you use.

Features

• Interactive setup wizard — a console TUI that detects missing API keys and guides you through configuration
• Console quality/price chart — somm chart prints a Pareto-frontier view of every OpenRouter model (any provider, not just OpenCode Go/Zen) ranked by price, marking the ones with the best quality for their price
• List available models from OpenCode Go/Zen subscriptions
• Cross-reference with OpenRouter benchmarks and pricing
• Read agent selection criteria from the Gentle AI guide
• Search specific model benchmarks
• Recommend optimal model configuration per agent role
• Estimate monthly costs by agent
• Compare models side-by-side
• Validate current configuration
• Export safe config to opencode.json (only the model field)
• Automatic .env configuration loading
• HTTP timeout, retry, and graceful degradation
• Multi-provider support — OpenCode and OpenRouter

Installation

Using Go

go install github.com/R0LM0/somm/v2/cmd/somm@latest

From Release

Download the latest binary from Releases.

From Source

git clone https://github.com/R0LM0/somm.git
cd somm
make install

Configuration

Quick setup (recommended)

Just run somm — if no API keys are configured, the setup wizard launches automatically:

somm

The wizard will:

1. Check if you already have API keys configured
2. Ask which providers you want to use (OpenCode required, OpenRouter optional)
3. Guide you through pasting each API key
4. Save the .env file and update opencode.json
5. Start the server automatically

Manual setup

If you prefer manual configuration, see the options below.

Environment variables

Variable	Required	Description
OPENCODE_API_KEY	Yes	OpenCode Go/Zen subscription key
OPENROUTER_API_KEY	No	OpenRouter API key for benchmarks
SOMM_PROFILE	No	Path to a role profile YAML file (see Role profiles)

.env file

Create a .env file next to the binary:

OPENCODE_API_KEY=sk-your-key-here
OPENROUTER_API_KEY=sk-or-your-key-here

Flags

somm -opencode-api-key sk-xxx -openrouter-api-key sk-or-xxx -profile ./somm.yaml

Non-interactive mode

For CI/scripts, use --skip-setup to fail with a clear message instead of launching the wizard:

somm --skip-setup

Role profiles

Recommendations are driven by a Profile: a list of roles, each with scoring weights over intelligence/coding/agentic benchmarks and optional hard constraints (min_context, max_input_price, requires, exclude_family_of). By default, Somm ships the gentle-ai preset (the original 19-role taxonomy) embedded in the binary — no configuration needed.

The active profile is resolved in this order, using the first source found:

1. -profile <path> CLI flag
2. SOMM_PROFILE environment variable
3. ./somm.yaml in the current working directory
4. $XDG_CONFIG_HOME/somm/somm.yaml (or ~/.config/somm/somm.yaml)
5. the embedded gentle-ai preset

A malformed or invalid profile file at any of these sources fails loud — the server does not start with a silently-substituted default. Bring your own roles with a YAML file like:

version: 1
defaults:
  min_context: 32000
roles:
  - id: my-agent
    description: "needs strong coding + a context floor"
    criticidad: "CRÍTICO"
    weights:
      coding: 0.7
      intelligence: 0.3
    max_input_price: 5.0
    requires: ["reasoning"]

Usage

First run

Just run somm — the auto-setup wizard handles everything:

somm

If API keys are missing, you'll see the setup wizard. If already configured, the server starts immediately.

Setup wizard (manual)

You can also run the wizard explicitly:

somm setup

To reconfigure an existing installation:

somm setup --force

Console quality/price chart

somm chart prints a ranked, ★-marked Pareto-frontier view of the full OpenRouter catalog — no OPENCODE_API_KEY required, since OpenRouter's model list is public:

somm chart                              # Pareto-optimal models by intelligence/price
somm chart --metric coding              # rank by coding score instead
somm chart --provider anthropic         # filter by provider or model name
somm chart --all --top 50               # list every priced model, not just the frontier

With OpenCode (manual)

Add to your opencode.json:

{
  "mcp": {
    "somm": {
      "type": "local",
      "command": ["path/to/somm"],
      "enabled": true
    }
  }
}

MCP tools

Example outputs below are illustrative — model names and numbers depend on the catalogs reachable with your keys at query time.

list_available_models

Fetch all available AI models from your subscriptions.

Parameters:

• subscription: "go" | "zen" | "both" (default: "both")
• enrich: boolean (default: true) — cross-reference with OpenRouter

get_agent_criteria

Read the Gentle AI agent selection criteria.

Parameters:

• agent: string (optional) — filter by agent ID

Available agents:

• Orchestrator: gentle-orchestrator
• SDD: sdd-init, sdd-onboard, sdd-explore, sdd-propose, sdd-spec, sdd-design, sdd-tasks, sdd-apply, sdd-verify, sdd-archive
• Review: review-risk, review-readability, review-reliability, review-resilience, review-refuter
• Judgment Day: jd-judge-a, jd-judge-b, jd-fix-agent

get_model_benchmarks

Search OpenRouter for detailed benchmarks.

Parameters:

• query: string — model ID or name

estimate_cost

Estimate monthly cost based on model usage patterns.

Parameters:

• hours_per_day: number (default: 8) — average usage hours per day
• roles: string[] (optional) — filter specific agent roles

compare_models

Compare models side-by-side with benchmarks and pricing.

Parameters:

• models: string[] (required) — 2–4 model IDs to compare

validate_config

Validate the current configuration and suggest improvements.

Parameters: none

export_config

Export the recommended model configuration to opencode.json. Safe: only updates the model field.

Parameters:

• roles: string[] (optional) — filter specific roles

recommend_config

Detect configured providers and recommend the optimal model per agent role, with the reasoning behind each pick.

Parameters:

• roles: string[] (optional) — filter specific agent roles

Development

Prerequisites

• Go 1.26+

Commands

make build         # Build with version info
make test          # Run tests with coverage
make lint          # Run go vet
make install       # Install to GOPATH/bin
make cross-compile # Build for all platforms
make clean         # Remove binaries
make fmt           # Format code
make tidy          # Clean dependencies
make all           # Full pipeline (fmt, tidy, lint, test, build)

Project structure

cmd/somm/          # MCP server entry point (serve, setup wizard TUI, chart)
internal/api/      # HTTP client, models, matching, recommendations
internal/guide/    # Embedded guide extraction
internal/profile/  # Role profile schema, presets, resolution

Release

Pushing a v* tag triggers GoReleaser via GitHub Actions, which builds and publishes cross-platform binaries automatically:

git tag v2.3.1
git push origin v2.3.1

License

MIT © R0LM0 — see LICENSE.