Configuration

Where settings live, and which one wins

Configuration comes from several places, and they stack. Each level overrides the one before it, so the same key can be set broadly and then narrowed for a specific machine or a single run. From lowest to highest precedence:

• Built-in defaults, sensible values shipped with Squeezy, so an empty config still works.
• User settings ($SQUEEZY_HOME/config/settings.toml), your personal defaults across every project: provider, model, theme, anything you want everywhere.
• Project settings (squeezy.toml), committed with the repo and shared by the team: indexed languages, include/exclude rules, permission rules, budgets. Squeezy reads the nearest squeezy.toml up the directory tree.
• Per-project Local settings ($SQUEEZY_HOME/projects/<project-id>/config/settings.toml), your personal overrides for one repository that shouldn't be committed, like machine-specific paths.
• Environment variables, override config for a shell or a CI job without editing any file.
• CLI flags, highest precedence, applied to a single invocation (for example, --mode plan).

User vs project: what goes where

The split is about who the setting belongs to. Personal preferences (which model you like, your theme) go in your user settings so they follow you across projects. Shared, repo-specific policy (the languages to index, what shell commands are allowed, output budgets) goes in the project's squeezy.toml so the whole team gets the same behavior on checkout.

Per-repo user settings sit in between: tied to one repository but kept on your machine. They're the right home for things that matter but aren't shareable, like an extra local directory you want the shell sandbox to be able to read.

Seeing the merged result

Because settings come from several layers, it's easy to lose track of what's in effect. Two commands answer that. config inspect prints the final, merged configuration as valid TOML and lists the source chain, so you can see which layer contributed each value. doctor validates your configuration and likewise shows the resolution chain, the fastest way to find a typo or a value being overridden somewhere you didn't expect. Both outputs are safe to share: anything that looks like a secret is redacted.

squeezy config inspect      # merged config + source chain, redacted
squeezy doctor              # validate config, show resolution chain
squeezy config init --user  # write a commented starter user file

The settings you're most likely to change

Most customization touches a small set of knobs. Each line below is one thing you can change and what it does:

• Provider and model, which service and model handle your turns. First run walks you through picking these and saves the choice; you rarely edit it by hand.
• Profile / reasoning effort, a tradeoff dial between speed/cost and depth of reasoning, sent only to models that support a native reasoning control.
• Permissions mode, how much Squeezy can do without asking: default, auto_review, full_access, or custom. Covered in depth on the permissions page.
• Turn routing on/off, send easy turns to a cheaper model while hard turns stay on your main model. On by default; toggle with /router.
• Squeezy experimental opt-in, a default-off Tools setting for cutting-edge Squeezy features. No feature uses it today, so enabling it changes nothing yet; User and per-repo Local settings may enable it, but committed Project settings cannot.
• Response and tool-output verbosity, how long answers are, how much of a tool's output is previewed, and whether the status footer stays compact.
• Telemetry opt-out, stop anonymous usage data from being sent.
• Context and limit knobs, compaction that summarizes stale history once a prompt grows large, and per-turn budgets that cap how many tools run and how much output they return.

An annotated example

Here is a small user settings file with every line explained. You only need to set what you want to change, leaving a key out keeps the built-in default, which is why the generated starter files ship as commented examples.

[model]
provider = "openai"           # which provider handles your turns
profile  = "balanced"         # speed/cost vs. depth tradeoff
reasoning_effort = "medium"   # how hard reasoning-capable models think

[agent]
experimental = false          # no Squeezy feature uses this gate today

[routing]
enabled = true                # route easy turns to a cheaper model

[permissions]
mode = "auto_review"          # let the AI reviewer pre-screen eligible prompts

[context]
compaction_enabled = true     # summarize stale history once the prompt grows large

[telemetry]
enabled = false               # opt out of anonymous usage data

[tui]
response_verbosity    = "normal"   # answer length
tool_output_verbosity = "compact"  # how much tool output is previewed
theme = "starlight"                # default, bright, fun, starlight

Telling Squeezy a model's limits

Squeezy resolves each model's context window and output cap from a layered chain: an explicit override you set, a live probe where the provider supports one, its bundled catalog, the shared models.dev catalog, and a conservative fallback. For a model it has no entry for, common when you point a gateway like OpenRouter, Portkey, or Vercel at a brand-new model, you can pin the numbers under [model_limits] so it plans against the correct window instead of a guess. An unset value stays automatic, and an unrecognized model behind a gateway keeps working either way.

Use context_window when Squeezy's catalog is wrong or missing for a specific provider:model. It pins Squeezy's assumed model capacity for /context, input-budget estimates, and compaction, but it does not shrink or enlarge what the provider can accept.

Use budgets.max_round_input_tokens when the catalog is right and you want a hard cost/safety cap on the input tokens Squeezy will try to send in a round.

The model.context_1m flag is different again: it only sends Anthropic's legacy context-1m beta header on Anthropic/Bedrock requests, and the config screen hides it for other providers because it is ignored there. Current Claude Sonnet 4.6 and Opus 4.6+ models are cataloged as 1M by default and do not need that header.

Local models served by Ollama add one knob: num_ctx sets the loaded context length the server allocates per native request, and Squeezy plans /context, preflight estimates, and compaction against that same number so the budget it shows matches what the server serves. Raise it to give a large-window local model its full window when you have the memory, or lower it for a small model on a tight machine. You can also set both keys from the /config screen.

[model_limits."openrouter:vendor/new-model"]
context_window = 256000   # use when catalog is wrong/missing
max_output = 32000        # most output tokens the model can produce

[budgets]
max_round_input_tokens = 200000  # hard cost/safety cap on sent input

[model]
context_1m = false       # Anthropic/Bedrock context-1m beta header only

[providers.ollama]
num_ctx = 131072          # loaded context length for local /api/chat (also OLLAMA_NUM_CTX)
keep_alive = "30m"        # how long the server keeps the model loaded

Keeping secrets out of config

Prefer environment variables or Squeezy's protected credentials file. Inline api_key values are supported, but they are stored as plaintext in User or Local settings, so do not place them in a shared squeezy.toml. With api_key_env = "OPENAI_API_KEY", Squeezy reads the secret from that variable at runtime and config inspect can report the variable name without exposing the value.

This indirection is also what first-run setup writes: when it detects an available provider key, it saves the variable name into your user settings, not the secret. On top of that, redaction is always on, keys, tokens, and credential-looking values are masked everywhere they could appear, so a secret that slips into command output doesn't leak.

Related

• Permissions & safety
• Right-size every turn
• Install & upgrade