Teach crystl your models once

Updated August 15, 2026

Goal: fill in what small, standard, and large launch 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 size holds the complete command you would type in a terminal, which is the form to reach for whenever 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. A bare model id like the codex example above still works: crystl composes it into a command through that agent’s known convention, and rewrites it as the full command the next time you edit the profile. Only the sizes you pass change, so you can do one now and the rest later. Passing an empty string clears one.

    Any of these can name an open-model connection with model@endpoint, including inside a command’s own flag: --standard 'claude --model glm-4.6@glm'.

    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 has one row per native profile or configured exact command, and small, standard, and large are properties of that agent. Each size field accepts a complete start command or a bare model id; custom and exact full-command rows also have MODEL VIA for bare model ids.

  5. Set the fallbacks too. Settings → agents → defaults holds exactly three raw launch commands, one per size. Those are what run when nothing names an agent, which is the case for an unassigned hero, quest member, or fan-out worker.

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 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 pin, or --model on the summon), then the size, through the named agent’s own three or the three defaults, then nothing.

Go deeper