Docs > Start

Providers and keys

This page describes which model Shift talks to, how to choose a different provider or model, where a provider's key comes from, and how Shift keeps a conversation inside the model's context window. Shift ships with a local Ollama model selected, so the first launch needs Ollama running with that model pulled, a provider key from this page, or the demo model described in Install and first session.

The default: a local Ollama model

The agent file sets the provider to ollama, the model to qwen3.8:27b-mlx, and the endpoint to Ollama's standard local address. No key is configured: agent-api-key-environment is #f. To start with the default:

1. Start Ollama.
2. Confirm the model is installed with ollama list.
3. Run shift-agent.

In Ollama's local metadata, the default model advertises completion, tool calling, thinking, vision and a 262K context window. It was chosen over a 104 GB alternative to keep interactive work practical.

Output streams by default and thinking is hidden by default. /thinking, /thinking medium and /thinking off change the thinking level; /stream off and /stream on control streaming. The same choices are live Scheme settings: agent-thinking takes #t, #f or one of 'low, 'medium and 'high, and agent-stream? takes a boolean. agent-keep-alive is sent to Ollama as keep_alive and defaults to "10m", long enough for a normal pause without pinning the model.

To try the interface without any model, set the model to demo:

shift-agent --session ui-demo --set 'agent-model="demo"'

Choose a provider and model

To see what the current provider offers, enter /model list. Shift asks Ollama's tag endpoint or the provider's models endpoint; this is a metadata request with no inference. The sidebar's Model tab shows the same list, marks the current provider/model, and switches when you click a row.

To switch, enter:

/model PROVIDER/MODEL

Naming the provider selects it together with its standard endpoint. The picker does not infer a provider from an ambiguous model name, so name it. /model NAME at the prompt Tab-completes the listed names. Choosing another model of the current provider keeps that provider's endpoint and key source, so a local OpenAI-compatible server stays selected; choosing another provider restores that provider's defaults. A running turn or a pending approval refuses the switch without consuming your input. The session checkpoint keeps the selection across restarts.

Claude is a built-in native adapter with streaming text, thinking, signed thinking blocks, tool calls and usage. Switching between providers mid-session keeps tool call IDs intact; blocks that only Claude understands are kept for the model that produced them and left out when the conversation goes to another provider.

Supply a key

Keys come from the environment of the process, never from the agent file. Claude reads CLAUDE_API_KEY and OpenAI reads OPENAI_API_KEY. Export the variable before you launch shift-agent. Settings and checkpoints store only the variable's name, so a saved session never contains the key itself, and after a restart the environment still has to hold it.

The agent-api-key-environment setting names the variable a provider reads. It is #f for the Ollama default and takes a string such as "OPENAI_API_KEY" for a remote provider.

For OpenAI specifically, the checked-in openai-gateway extension selects gpt-5.4-mini at OpenAI's endpoint without changing the repository's Ollama default. With the key exported, enter /extension-load openai-gateway in a session.

Use a custom endpoint

Any OpenAI-compatible gateway works through the openai provider. Set the endpoint and the key variable with the typed agent-base-url and agent-api-key-environment settings in the project's .shift/settings.json before launch, or redefine them live:

/eval (define agent-provider 'openai)
      /eval (define agent-base-url "https://your-provider.example/v1")
      /eval (define agent-api-key-environment "OPENAI_API_KEY")

Requests to a generic OpenAI-compatible endpoint support SSE streaming and streamed function calls.

Set effort and speed

/effort and /fast are independent preferences. For known Claude models, Shift sends output_config.effort and speed: fast; for known OpenAI reasoning models it sends reasoning_effort and service_tier: fast. The mappings are deliberately conservative. A preference the current model does not support is kept, shown as unavailable, and left out of the request. OpenAI manages its own thinking, so /effort is the control there; no separate thinking toggle goes to OpenAI Chat Completions.

Watch the context window

Enter /context to see the last request's estimated input, the known context limit, the output reserve and the usage the provider reported. The sidebar shows the same as a segmented bar with a compact count such as 24k / 131k.

The estimate counts tool schemas and message framing and is not a tokenizer count. The first request of a turn estimates bytes divided by three; later tool rounds scale that by the ratio of the provider's last reported prompt count to the raw estimate for the same request. Cache reads count toward context size. A 20% margin and the output reserve apply on top; the output-reserve setting defaults to 8192.

Claude's window is discovered from the account's model metadata. For a local Ollama model, a bounded metadata request supplies the loaded model's context length; architecture maximums are never substituted. If a provider does not report its window, the limit stays unknown and the bar shows ?. To set it yourself, enter:

/context limit TOKENS

An explicit limit wins over anything discovered. Switching models clears it.

Compaction

Before each request in a tool loop, Shift checks the conversation against 80% of the input-plus-output budget (agent-compaction-threshold). When it is over, Shift first asks the model to save its progress, decisions, unresolved work and exact paths with the notes tool, into the session's notes/ folder and never into the project. It then replaces the earlier context with a pointer that lists those files and reminds the model that traces and recall still reach earlier turns. If the model writes no note, Shift summarizes the earlier complete turns instead, keeping the current turn and its tool chain. If even the retained turn cannot fit, the run pauses with an error and the checkpoint is preserved. /compact runs the same step on demand. Every compaction writes what it replaced beside the checkpoint as compactions/N.json, and raw usage stays in the local traces.

Reference

What's next

• The agent file for the rest of the settings and how to change them live.
• Sessions for checkpoints, notes and what a resumed session remembers.
• The terminal for the Model tab and the context bar.