settings

Configuration

Squeezy reads plain TOML settings files. Your own defaults live in one file that follows you everywhere, a project can commit shared settings beside its code, and a single run can override either without editing anything. This page shows where each file lives, which one wins when they disagree, and the settings people actually change.

contents

Where settings live, and which one wins

Ordinary settings resolve through the layers below, from lowest to highest precedence. A higher applicable layer supplies the value; omitted keys inherit. Squeezy records the effective source. Provider inputs can have their own fallback order: an authored Bedrock provider_profiles.<name>.region wins over AWS_REGION and AWS_DEFAULT_REGION.

Built-in defaults supply values that no other applicable layer sets.
Your settings ($SQUEEZY_HOME/config/user-settings.toml). Personal defaults across every project: which model does your work, your theme, how much Squeezy may do without asking.
Project settings (squeezy-settings.toml). Shareable preferences from the nearest file in the directory you start in or any directory above it. The file can be outside the Git repository; check the resolved path before sharing it.
Machine-local settings ($SQUEEZY_HOME/projects/<project-dir>/config/local-settings.toml). Private settings for this checkout on this machine, including paths that only exist here.
Declared environment overrides. Change a setting for one launch without editing a file. The launch environment is captured once; relaunch after changing it.
Command-line flags, such as --build-base-model, apply for the launch. --mode selects the starting Mode; the running Session owns later Mode changes.
Session choices, highest of all, support model assignments and temporary Build variations. They do not write a settings file and survive resuming the conversation; this scope does not support every setting.

What a project's settings are allowed to change

A checked-in squeezy-settings.toml is a file you may not have written, so it does not carry the same authority as your own. It can make a session stricter, never looser. It can tighten permissions, lower a cost or concurrency ceiling you set, and shorten how long session logs are kept. It cannot widen access past your ceiling, raise a cap, arm hooks, or move where session logs are written.

Provider profiles, Model profiles and role assignments in a Project file require trust in their exact non-secret route content before they can apply. They are not rejected merely because they came from Project. Credentials stay in protected storage; a trusted route may name their source but cannot put a secret into settings TOML.

Nothing is dropped silently. Every field the loader ignores or clamps is reported with its path and the reason it lost.

Seeing what is actually in effect

With several layers in play it is easy to lose track of the effective value. squeezy config dump prints the merged configuration as TOML. squeezy config show <key> reports one value and its source; squeezy config explain <key> adds the layer stack and apply timing. squeezy config validate reports ignored, clamped and unknown authored settings; --strict fails when the running value does not honor what the file asked for.

Configuration diagnostics mask secret fields rather than printing stored credentials.

squeezy config dump                    # merged config + the layers it came from
squeezy config show model.provider     # one value, and who set it
squeezy config explain model.provider  # the same, plus what it shadows
squeezy config validate                # anything ignored, clamped, or unknown
squeezy config init --user             # write a commented starter file

The settings most people change

Customization usually touches a short list. Everything here is also editable inside the terminal with /config, which writes the same files.

Which model does the work. First run asks for the provider, the exact model, and how hard it should think, then saves that as a named model config with a role pointed at it. You rarely edit it by hand afterwards.
How hard the model thinks. reasoning_effort is a hint sent only to models that expose a reasoning control, and the picker offers the levels the chosen model actually has.
How much Squeezy may do without asking. permissions.access selects ask, auto, full or custom. A named Access profile is selected with { profile = "name" }; it is separate from Mode. The permissions page explains each choice.
Turn routing chooses Cheap, Main or Expensive as the work requires. routing.cheap_route, routing.expensive_route and routing.judge_route can name Model profiles or service/Base-model references. Without explicit destinations, supported routes use provider-aware defaults and otherwise stay on Main. Open /router to inspect and change them.
How much you see. responses.detail guides model answer detail; tui.tool_output_verbosity controls inline tool previews, and status detail has its own setting.
Telemetry. Anonymous usage reporting is on by default and off with one key.
Ceilings. Caps on tool calls, bytes read, and dollars spent in a session, plus the compaction that summarizes stale history once a conversation grows large.

An annotated example

A small User settings example. Set only the overrides you need; omitted values inherit. In a generated starter, uncomment the section header as well as the keys you want to set.

A Model profile is a named recipe: Provider profile, Base model and generation controls. The roles table assigns Build, Plan, Orchestrate and Utility. Plan and Orchestrate follow Build when not assigned separately.

[model_profiles.work]
provider_profile = "openai"     # Provider profile name
base_model = "gpt-5.6-sol"       # exact Base model ID
reasoning_effort = "medium"     # use a level the Base model supports

[roles]
build = "work"                  # Model profile used by Build

[provider_profiles.openai]
authentication = { primary = { source = "environment", name = "OPENAI_API_KEY" } } # exact launch variable

[model_profiles.quick]
provider_profile = "openai"
base_model = "gpt-5.6-terra"

[routing]
enabled = true
cheap_route = "quick"           # explicit Cheap destination

[permissions]
access = "auto"                 # ask | auto | full | custom

[context]
automatic_full_compaction_enabled = true

[telemetry]
enabled = false                 # disable usage reporting

[responses]
detail = "normal"               # concise | normal | verbose

[tui]
tool_output_verbosity = "compact" # compact | normal | verbose
theme = "gold"                   # /theme lists available palettes

When Squeezy does not recognize your model

To plan a turn, Squeezy needs two numbers about the model: how much it can hold, and how much it can write back. It resolves both through a layered chain -- an override you set, live metadata where the provider publishes it, its own bundled catalog, a cached public catalog, and finally a conservative guess. Point a gateway at a model released last week and the guess is what you get.

Base model facts can override missing or incorrect catalog data for an exact service and Base model ID. context_window affects Squeezy’s local context calculations; it does not increase what the provider accepts. limits.max_step_conversation_tokens separately bounds estimated conversation tokens per model step, excluding fixed instructions and tool definitions. It is not a cap on every byte or token in the full provider request.

A model you run locally through Ollama has one more knob. num_ctx is the context length the server loads for a request, and Squeezy plans against that same number, so the budget it shows matches what the server will serve. 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.

[base_model_facts."openrouter:vendor/new-model"]
context_window = 256000         # local fact override, not a provider entitlement
max_output_tokens = 32000       # model output-limit fact

[limits]
max_step_conversation_tokens = 200000 # excludes fixed instructions and tool definitions
session_cost_budget_usd = 25.50       # dollars; omit to inherit (default: no limit)

[provider_profiles.ollama]
num_ctx = 65536                 # context loaded by the local server
keep_alive = "5m"               # time the server keeps the model in memory

Keeping keys out of your settings files

Provider profiles choose one source in authentication.primary. A stored source names a protected store and key; an environment source names one exact variable, as in the example above. Settings contain references, never secret values. A missing selected credential is an error.

Run squeezy auth set -- openai to store a key and select its protected source. A new key uses User storage; an existing stored selection keeps its scope. Add --local for this checkout's private storage. Updating a shared key affects every profile linked to it.

Agent and Session masking is enabled by default. redaction.enabled can disable that masking at the next prompt; existing markers are not rewritten. Configuration and authentication diagnostics, protected credential storage, feedback and support output retain their independent sanitizers.

squeezy auth set -- openai              # read stdin; store and select the protected source
squeezy auth set --local -- work-openai  # checkout-local protected storage
squeezy auth status -- openai           # report the source without printing the value

Bring a key in from a secret manager

Pipe a secret manager's output into squeezy auth set instead of putting a command or a secret value in TOML. With no --value argument, auth set reads stdin so the key does not appear in shell history. The protected store remains the only durable secret-bearing file.

For CI or a single launch, select source = "environment" and name = "OPENAI_API_KEY" in authentication.primary, then provide that variable when you launch Squeezy. The selected source is exact: another variable or stored key cannot supply fallback authentication.

op read op://Engineering/OpenAI/credential | squeezy auth set -- openai
vault kv get -field=api_key secret/llm/openai | squeezy auth set -- openai

# For a profile explicitly selecting OPENAI_API_KEY as its environment source:
OPENAI_API_KEY=... squeezy

the contents list reaches every page in the docs