Models & Allocations
pw code can run on any chat model your AI providers offer, on inference servers you configure locally, and on a Claude Code subscription. This page covers how models are identified, how to discover and switch between them, and how budget allocations work for organization providers.
Model IDs
Model IDs have the form owner:provider-name/model-name:
- Personal providers are addressed by their owner's username, for example
Jake.Thayne:openai/gpt-5.2. - Your own connected subscriptions (such as a ChatGPT/Codex subscription connected with
pw ai codex connect) appear under your username, for examplealice:personal/gpt-5.2-codexfor a provider namedpersonal. - Organization providers use the
org:owner (for exampleorg:openai/gpt-5.2) and require a budget allocation.
An ID passed to pw code must contain a /; anything else is rejected as an invalid model format.
Two more kinds of ID select models outside your AI providers: inference-server/<name>/<model> for a locally configured inference server, and Claude model names for a Claude Code subscription.
Discovering Models
List every model available to you across all configured providers:
pw ai models ls
# As JSON, for scripting
pw ai models ls -o jsonThe Interactive Model Picker
If you start pw code without specifying a model, the model picker opens automatically. You can also open it any time in a session by running /model with no arguments, or from the Model row in /settings.
In the picker:
- Grouped by provider: each row shows the friendly name and the full model ID. Models from your inference servers and your Claude Code account appear in the same list. A provider whose connection is broken (for example, a bad API key) shows a warning on its heading, and its models can't be picked until you fix it and refresh.
- Type to filter: the list narrows as you type, matching against both the model ID and its display name.
- Select or dismiss: Enter selects the highlighted model; Esc first clears an active filter, then closes the picker.
- Refresh: Ctrl+R refreshes the list from the platform; the fetched list is cached for the rest of the session.
Switching Models In-Session
Use the /model slash command:
# Open the interactive picker
/model
# Switch directly to a specific model
/model Jake.Thayne:openai/gpt-5.2The new model applies to all subsequent turns in the conversation. Switching keeps the same conversation, even between an AI provider model, an inference server model and a Claude model. A change made while a turn is running waits for that turn to finish, and the confirmation says (applies to the next turn).
Which Choices Persist
- A model chosen from the picker is saved as your default and is used the next time you start
pw codewithout specifying a model. - A model set by typing
/model <model-id>applies to the current session only. - Allocation choices persist either way, whether picked from the allocation picker or set with
/allocation <name>. - A reasoning effort set with
/effortpersists as your default;--effortapplies to that session only. - The permission mode cycled with Shift+Tab persists the same way; see Permissions.
Defaults are stored in your pw code settings and can also be set per project. See Settings.
Allocations
Models from organization providers (org: IDs) draw their spend from a budget allocation. Personal provider models do not use allocations.
On the command line, pass the allocation name with the --allocation flag:
pw code --allocation PW-QA-TEST org:openai/gpt-5.2Choosing an Allocation Interactively
In an interactive session, you never have to know the allocation name up front. When you select an organization model (or send a message with one active) and no allocation is set, pw code fetches the allocations you are permitted to use and prompts you to pick one. Each row shows the allocation's spend so far against its total budget. You can also open the picker at any time with /allocation, or change it directly with /allocation <name>.
If no allocations are available to you, pw code reports it and asks you to contact your organization admin for access.
Allocations in One-Shot Runs
A one-shot (non-interactive) run cannot open a picker. It uses --allocation when given, and otherwise your saved allocation. With neither, an organization model fails immediately:
an allocation is required for org provider models. Use --allocation to specify one.
Run 'pw code' without --prompt to browse available allocations interactively.Reasoning Effort
Models that reason before answering can be asked to think more or less. Pass --effort at launch, or change it in a session with /effort:
pw code --effort high Jake.Thayne:openai/gpt-5.2# Open the effort slider (← and → to move, Enter to choose, Esc to cancel)
/effort
# Set it directly
/effort lowThe levels, from fastest to most thorough, are none, minimal, low, medium, high, xhigh, and max. default sends no level and leaves the choice to the provider. Support varies by model: the slider and /effort offer only the levels the current model accepts, when the platform knows them.
A level chosen with /effort is saved as the effort setting and used for new sessions; a resumed session keeps the level it had. --effort overrides both for one session.
The status line shows the effort next to the model name. If the model rejects the level, pw code retries the request without it and marks the effort (dropped); /status shows whether the level was applied, and as what.
While a model reasons, the transcript shows a Thinking block. When it finishes, the block folds into a one-line summary such as Thought for 12s, or the heading of the model's reasoning summary when it writes one. Press Ctrl+O (verbose mode) to expand it.
Automatic Retries
When a request fails for a reason that is likely to pass, such as a dropped connection, a rate limit (HTTP 429), a server error (5xx), or an overloaded provider, pw code retries it automatically, up to 10 times. The wait starts at about 1 second and doubles each time, up to 30 seconds, with some random variation. The transcript shows each failure, the attempt number, and the wait. If part of a response had already streamed, it is discarded before the retry.
A few failures get a different retry instead:
- Unsupported reasoning effort: retried without the effort level.
- Unsupported reasoning summaries: retried without them.
- Tool calling fails for the model: retried in chat-only mode.
- Context too long: the conversation is compacted and the request retried.
When the provider says how long to wait (up to 2 minutes), pw code waits that long instead.
Usage Limits
If a provider reports that a usage limit was reached and that it resets within about a day, the turn waits for the reset and then resumes on its own instead of failing. See When a Usage Limit Is Reached.
Interrupting the turn (Esc) stops any pending retry or wait.
Using a Personal ChatGPT/Codex Subscription
You can connect a personal ChatGPT/Codex subscription as an AI provider and use its models in pw code:
pw ai codex connect --name personalThis starts a device-code sign-in: open the printed URL, enter the code, and authorize. Once connected, the subscription's models become available as <your-username>:personal/<model>, and usage draws on the subscription's own quota rather than a platform budget.
- Reconnect:
--reconnectre-authorizes an existing provider without changing its identity. - Quota: check the subscription's usage windows from inside a session with
/usage.
For other provider types and sharing options, see AI Providers.
Locally Configured Inference Servers
pw code can connect directly to an OpenAI-compatible inference server, such as one running on your laptop or on a cluster node, without registering it as an AI provider. Configurations are saved for your user on the machine running the session, in ~/.config/pw/inference-servers.json; they are not stored on or shared through ACTIVATE.
# Discover the server's models from its /models endpoint
pw code inference-servers add --url http://localhost:8000/v1 lab
# Prompt for a token and save it in this machine's OS credential store
pw code inference-servers add --url https://inference.example/v1 --api-key cluster
pw code inference-servers list
pw code -m inference-server/lab/Qwen/Qwen3-Coder- URL: pass the API base URL, including
/v1or any other path the server needs. - Models: without
--model, the server's model list is discovered and refreshed with Ctrl+R in the picker. Pass--model(repeatable) to use a fixed list instead, for servers without a model list endpoint. - Tokens:
--api-keyreads a token without echoing it. On headless hosts or in CI, use--api-key-env NAME(a variable set where thepw codedaemon runs) or--api-key-file /absolute/path. Rotate a saved token withpw code inference-servers auth <name>. - Remove:
pw code inference-servers remove <name>deletes the configuration and its saved token.
Inference server models don't use allocations. Run these commands on the machine where the session runs: when you attach to a session on a remote host, configure the servers on that host. Features that need ACTIVATE, such as notebooks and remote control, still need an ACTIVATE connection. See pw code inference-servers for every option.
Claude Code Subscriptions
If Claude Code is installed and signed in with a Claude subscription on the machine running the session, pw code can run its turns on that subscription:
claude auth login
pw code --backend claude-code
pw code --backend claude-code -m sonnetClaude models also appear in /model, so you can switch an existing conversation to Claude and back. pw code keeps its own interface, permissions, tools, skills, hooks, plan mode and goals. A new session starts on Claude when the last model you chose in /model was a Claude model; --backend native, a provider --model or --allocation start on your AI providers instead.
- Sign-in: the subscription login must be a Claude account (
claude.ai) or an OAuth token. An API key or cloud-provider configuration is refused, and usage is never billed to an API instead. - Accounts:
/claude-codeopens the Claude Code panel, which lists your accounts with their five-hour and weekly usage and reset times. Press Enter to use an account, → for its usage, l to sign in, a to add one, d to remove one and Ctrl+R to refresh. The same actions are available as/claude-code login <name>,/claude-code use <name>and/claude-code remove <name>, and--account <name>picks the account for a new session.defaultis your own Claude Code login. - Usage:
/usageshows the selected account's subscription limits. - Organizations: an organization administrator can turn this off for all members with the
disableClaudeCodemanaged setting. Claude models then can't be selected, and Claude sessions can't start or continue.
Tool Calling Support
Not every model endpoint implements a tool-calling API, and pw code needs tool calling to read files, run commands, and edit your workspace. The gateway advertises each model as native, emulated, or none, shown in the "Tool calling" column of pw ai models ls:
- native: the provider's own tool-calling API is used.
- emulated: the provider has no tools API, so the gateway carries the tool contract in the prompt and reconstructs tool calls from the model's reply. The status line shows
emulated tools. Tools work normally; responses are not streamed incrementally and cost more input tokens per turn. - none: tool calling is unavailable. The status line shows
tools unavailableand the session is chat-only.
See Tool Calling & Emulation for the full mechanism and its limits.
Default Model for Subagents
Delegated subagent tasks can run on a different default model than your session, which is useful for pointing mechanical background work at a cheaper or faster model. Set it via the Subagent model row in /settings (the subagentModel setting); leave it empty to have subagents inherit the session's model. See Subagents for the full model resolution rules.
Related Documentation
- pw code Overview: Feature overview and quick start
- Settings: Where defaults are stored
- Slash Commands:
/model,/allocation, and more - Non-Interactive Mode: Model and allocation flags in scripts
- Subagents: Subagent model resolution
- Usage & Costs: Cost estimates, provider quotas, and compaction
- AI Providers: Configure AI providers
pw code inference-servers: Inference server commands and options- Tool Calling & Emulation: What
emulated toolsin the status line means