Teach crystl your models once

Updated August 12, 2026

Goal: fill in what small, standard, and large mean for the agent you run, once, so you stop typing model ids.

What you need

  • An agent installed and running in a shard. Profiles follow the exact launch command, with native sharing for bare seeded commands as described below.
  • Reading and writing the profile are free on every tier. It’s local machine config.

crystl ships no size-to-model table on purpose. Model ids churn, there are more agent CLIs every month, and a compiled-in list would be stale the moment a provider renames something. So the map is learned from you.

Steps

  1. See what’s already known:

    crystl agent profile
crystl agent profile show --agent codex

  2. Fill it in. Pick the agent’s cheapest and fastest setup for --small, its everyday default for --standard, and its most capable for --large:

    crystl agent profile set --agent codex \
  --small gpt-5.6-luna --standard gpt-5.6-sol --large gpt-5.6-terra

    A field can hold a bare model id or the complete start command for that size. Use a complete command when the setup also needs effort, a path, environment, or other arguments:

    crystl agent profile set --agent claude \
  --small 'claude --model haiku --effort low' \
  --standard 'claude --model sonnet --effort high' \
  --large 'claude --model opus --effort max'

    crystl preserves structured commands exactly. Put pipelines, redirects, substitutions, or command lists in a wrapper script. Only the sizes you pass change, so you can do one now and the rest later. Passing an empty string clears one.

    For a custom command using bare model ids, also tell crystl how to deliver the chosen model. MODEL VIA accepts a template with exactly one {model}: '-m {model}', '--model {model}', or 'MODEL={model}'. A complete command in the size field needs no template.

    crystl agent profile set --agent 'npx my-agent --fast' \
  --small model-mini --standard model-pro --large model-max \
  --model-via '--model {model}'

    crystl appends argument templates to the full command and prefixes the environment form. It never guesses an unknown CLI’s convention.

  3. Or let crystl read the list for you when the models come from an open-model connection you configured:

    crystl agent profile suggest --agent codex --slot closet-box

    It reads the models the endpoint serves, proposes a mapping, and waits for a yes. It never writes a profile unprompted.

  4. Or click it in. Settings → Agents → agents & models has one row per native profile or configured exact command. Each size field accepts a model id or complete start command; custom and exact full-command rows also have MODEL VIA for bare model ids. It’s the same tab where you pick the default command.

What you’ll see when it works

crystl agent profile prints the map, stored at ~/.config/crystl/agent-profiles.json. A bare seeded command resolves to its native profile, so recognized aliases such as agy and antigravity share one row. A user-owned path, arguments, leading environment assignments, wrapper, or full custom command gets a distinct exact profile. Exact profiles can inherit untouched native settings when crystl recognizes the executable, while their own overrides remain separate.

Summon a hero or launch a party at a size and it starts with that size’s model id or exact command instead of the agent’s default.

Nothing breaks if you skip the size map. A size is a hint that’s allowed to evaporate: with no profile, or no mapping for the requested size, crystl passes no model selection and the agent launches on whatever it’s configured to run. A custom command with a selected model still needs MODEL VIA; crystl warns or refuses instead of guessing its syntax.

Which model actually launches, most deliberate first: an explicit model (a hero’s pinned model, or --model on the summon), then the size mapped through the profile, then nothing.

Go deeper