Application Configuration

Every key below lives in your Polytoken configuration file (JSON5, TOML, or YAML). Collection keys list their child settings; <name> marks a value you name yourself.

Most settings are easier to change in the configurator (polytoken config ui). Edit the file by hand for the settings it does not cover.

For model request options, service_tier=priority is the canonical value and fast is accepted as an alias. With ChatGPT-subscription authentication, the provider server routes the effective service tier.

Full schema: JSON | YAML.

providers

Providers Polytoken can use, keyed by a name that models reference.

providers.<name>

Name	Type	Description
kind	one of: catalog, custom_anthropic_compatible, custom_open_ai_compatible, custom_open_ai_responses	Provider source: a built-in catalog entry, or a custom backend that speaks the Anthropic or OpenAI protocol.
kind.name	string	Catalog entry to resolve, such as anthropic, openai, or codex.
enabled	boolean	Controls whether providers.<name>.enabled lets Polytoken use this provider. Omit this key or set it to true to keep the provider available. Set it to false to keep the provider settings while removing the provider and its models from model choices and requests.
url	string	Base URL Polytoken sends provider requests to. Polytoken appends the endpoint path for the provider’s protocol, so enter the origin only (for example https://api.anthropic.com) for Anthropic Messages providers, or the versioned base (for example https://api.openai.com/v1) for OpenAI Chat Completions providers. OpenAI Responses accepts both the origin and a trailing /v1 (it is deduplicated automatically). For Azure OpenAI Responses, use https://<resource>.openai.azure.com/openai/v1 as the base, azure_api_key for auth, and the deployment name as the model name. The same base URL is also used to list available models. Overrides the catalog default for catalog providers, and is required for custom providers.
auth	one of: no_auth, static_key, codex_device, kimi_code_device	How Polytoken authenticates requests to the provider: no auth, a fixed key, or the OpenAI Codex device flow.
auth.key	string	Secret key value sent in the auth header, usually an environment reference such as ${OPENAI_API_KEY}. Leading and trailing whitespace and newlines are stripped when the key is loaded; every other character is preserved, so keys that contain dots (for example a z.ai key shaped like id.payload.sig) are valid.
auth.format	one of: bearer_token, anthropic_x_api_key, azure_api_key	Header scheme for the key (bearer_token, anthropic_x_api_key, or azure_api_key). Omit to use the provider’s recommended format.
auth.profile	string	Auth profile name that supplies tokens for the device OAuth login flow. Use the profile name you chose when running polytoken auth provider login --provider <provider-name> to authenticate.
protocol	enum	API dialect the provider speaks (for example anthropic_messages, openai_chat_completions, or openai_responses). custom_open_ai_compatible providers default to openai_chat_completions; set openai_responses explicitly only when the provider serves the OpenAI Responses API. custom_open_ai_responses providers default to openai_responses.
headers	map	Extra HTTP headers Polytoken attaches to every request sent to this provider. Use this to satisfy gateways or proxies that require custom headers, such as an internal routing token or a gateway-specific auth header. Header names must be valid HTTP header names. When a header name matches one Polytoken already sends per request, the per-request value takes precedence. Polytoken sends User-Agent: Polytoken v<version> by default on provider requests, and a configured User-Agent header replaces it.
cache_control_strategy	one of: provider_managed, anthropic_breakpoints	Controls how prompt caching is handled for Anthropic Messages API providers. Use provider_managed when the provider caches automatically server-side, or anthropic_breakpoints to emit explicit cache_control breakpoints for endpoints that forward to real Anthropic. Defaults based on the provider URL: first-party Anthropic uses anthropic_breakpoints, all others use provider_managed. Only meaningful for Anthropic Messages protocol providers.
prompt_cache_key	boolean	Controls whether OpenAI Responses and Codex providers use a stable per-session prompt cache key. Omit providers.<name>.prompt_cache_key or set it to true to enable the key. Set it to false when the provider does not support prompt cache routing.

models

Defines the models Polytoken can select, keyed by name. Each entry is a partial override: when the name matches a catalog model, Polytoken applies only the fields you set and inherits the rest; when it does not match, Polytoken builds a new model and requires you to name its provider. You can set any field, including the context window, reasoning controls, edit format, and tool batching. Set enabled to false to remove a model Polytoken would otherwise offer.

Entries can also target models a provider discovers at runtime. When the name matches a discovered model, Polytoken applies the entry as an overlay over the provider-reported configuration. If the provider has not reported the model yet, the overlay has no effect until the model becomes available. Explicit selections under the reserved modelgroups tier entries accept any configured model. The provider-reported capability list and class metadata guide automatic selection when a tier is unset.

models.<name>

Name	Type	Description
enabled	boolean	Set to false to remove a model Polytoken would otherwise offer; omit to leave the model available.
provider_name	string	Model identifier Polytoken sends to the provider. It can differ from the name you use in models.
variant	enum	Model family: claude, openai, gemini, or other. Polytoken uses it to pick provider-appropriate defaults.
class	enum	Size class a model belongs to (full, mini, or nano). Required for custom models that do not match a catalog entry.
max_tokens	integer	Absolute output token ceiling the provider catalog reports for this model. Polytoken uses it for validation only; the effective limit sent to the provider is max_output_tokens_per_turn.
max_output_tokens_per_turn	integer	Per-turn output token limit Polytoken sends to the provider. When omitted, Polytoken derives a default from the model’s context window. Must not exceed the model’s hard ceiling (max_tokens).
stop_sequences	string list	Stop strings Polytoken forwards to the provider so generation halts on a match.
provider	string	Provider backend this model runs on, which must match a configured provider; required for custom models.
reasoning	one of: no_reasoning, effort, thinking	Reasoning or thinking capability. Polytoken merges the fields you set with the selected model’s capability and keeps omitted fields unchanged.
reasoning.effort_set	string	Effort family for the model’s reasoning levels. Omit this field to keep the selected model’s effort family.
reasoning.can_disable	boolean	Whether the model can turn reasoning or thinking off. Omit this field to keep the selected model’s setting.
reasoning.levels	string list	Discrete effort levels the model accepts. Omit this field to keep the selected model’s levels.
reasoning.default_level	string	Default reasoning effort when you do not name one. Omit this field to keep the selected model’s default.
edit_format	string	File-edit format Polytoken exposes for the model. The default and search_replace formats provide file_read, hashline provides file_read_hashline with matching edit anchors, and patch provides file_read; omit the key to use the default.
context_window	integer	Context-window size in tokens, which Polytoken uses to decide when to compact and to derive the per-model compaction threshold. Required for every model; omitting it produces a validation error.
compaction_threshold	number	Share of the context window at which compaction triggers for this model. When omitted, Polytoken computes it from the model’s context window and the per-tier compaction reserve, rounded down to two decimal places. When max_output_tokens_per_turn is also set, the reserve grows to accommodate it. Set to a value in (0.0, 1.0].
compaction_strategy	string	Selects local text summarization or the provider’s native compaction operation. Omit this key to use the catalog choice, or local when no catalog choice exists.
tool_loading	one of: eager, native_deferred, no_tools	How Polytoken exposes tools to the model: from the first turn, on demand, or not at all.
supports_vision	boolean	Whether the model accepts image inputs and can see image content in tool results. Defaults to false for custom models.
forced_tool_choice_supported	boolean	Whether the model can handle forced tool_choice requests end-to-end. Set to false for models whose thinking mode creates gaps that break subsequent turns after a forced tool call. When false, Polytoken uses a reminder message instead of forcing a tool call. Defaults to true.
max_tool_batch_size	integer	Maximum number of counted, non-exclusive tool calls the model may issue in one assistant message. When omitted, Polytoken uses eight calls. Set a positive value to choose a different limit for this model.
request_option_defaults	map	Request options Polytoken applies by default when it calls this model. Omit the key or leave it empty to use provider defaults.
inherits	string	Names the model whose provider identity, class metadata, context window, and request defaults this model inherits. The child keeps any explicitly authored request options and replaces matching parent keys. Omit the key to keep the model independent.
cache_warming_interval_secs	integer	Seconds between background prompt-cache refresh requests for this model. Omit the key to inherit the model’s catalog default (most models default to disabled). Set to 0 to disable refreshes for this model. Set to a value from 1 to 86400 to enable refreshes at that interval. Values outside that range reject the configuration. Only OpenAI Responses and Codex models act on an interval; other models keep the setting for portability but never warm.

facets

Sets the source for a named facet, overriding auto-discovery. A facet is a pre-prompted mode such as plan or execute. Each entry’s source is a shipped polytoken:// reference or a project-relative file path that stays within the project.

Explicit sources take precedence over the built-in facets and over any facet files Polytoken discovers in its facet directories.

facets.<name>

Name	Type	Description
source	string	Definition source for this facet or subagent: a shipped polytoken:// reference, or a project-relative file path that stays within the project.

daemon

Name	Type	Description
log_level	enum	Verbosity of Polytoken’s diagnostic logs.
max_tool_turns	integer	Maximum number of tool round-trips a single turn may run before Polytoken ends the turn. Omit to use the built-in default; Polytoken treats zero as unset.
provider_stream_idle_timeout_secs	integer	Seconds to wait for the next chunk from a provider stream before Polytoken treats the stream as stalled. When the stall fires, Polytoken collates whatever partial content arrived so far, persists it, and retries the provider request with that content in context rather than hanging indefinitely. Omit to use the built-in default; Polytoken treats zero as unset.
provider_stream_max_lifetime_secs	integer	Maximum wall-clock duration for a single provider stream before Polytoken proactively truncates it. When the limit fires, Polytoken preserves all partial content and continues the turn with a continuation prompt, avoiding upstream connection drops on long-running responses. Omit to use the built-in default. Set to zero to disable.
subagent_stall_threshold_secs	integer	Wall-clock seconds without subagent activity before Polytoken marks the subagent stalled and forces its provider stream to reconnect. Omit to use a value above the provider stream idle timeout so it only catches stalls the idle timer misses (such as a laptop sleeping on macOS). Polytoken treats zero as unset. Applied at daemon start; requires a restart to change.
max_concurrent_subagents	integer	Maximum number of subagents that may run concurrently. Additional subagents wait in reservation order until a slot opens. Omit this key for no limit; Polytoken treats zero as unset. Applied at daemon start; requires a restart to change.
subagent_liveness_watchdog_interval_secs	integer	How often Polytoken scans running subagents for stalled streams. Omit to use the built-in default. Polytoken treats zero as unset. Applied at daemon start; requires a restart to change.
follow_symlinks_for_configs	boolean	Whether Polytoken follows symlinks when loading configuration and context files such as AGENTS.md, skills, facets, subagents, project variables, and .agentblock files. On by default. When disabled, Polytoken skips symlinked files and shows a warning for each one. Applies to both the project .polytoken/ directory and the global configuration directory.
send_session_header	boolean	Controls whether Polytoken sends the X-Polytoken-Session header with model provider requests and requests to remote (HTTP) MCP servers. The header lets those services correlate traffic to the active session. On by default; turning this off stops sharing the session ID. Remote MCP servers pick up a change the next time the daemon starts. The X-Polytoken-Session name is reserved, so remote MCP servers ignore a configured header with that name even when this setting is off.
compaction_max_retries	integer	Maximum number of retry attempts when a compaction pass fails due to a provider error or empty summary. Each retry applies progressively more aggressive history stripping, and EmptySummary retries append a stronger instruction to the compaction prompt. Set to zero to disable retries. Omit to use the built-in default.
disable_context_clear	boolean	When on, Polytoken prevents clearing the working context. The /clear command and the plan handoff new-context option are disabled; compaction is not affected. Off by default.
disabled_tools	string list	A list of tool names that Polytoken completely removes from every conversation that uses this configuration. A disabled tool is never offered to the model, never appears in the tool listings visible to templates, and cannot be discovered through search. Use this to enforce strict “modes” that restrict what the model can do. A few tools are structurally required for Polytoken’s own lifecycle and cannot be disabled: exit_tool, progress_update, and tool_search. If you list one of these, Polytoken silently ignores the entry and emits a warning.
cache_warming	enum	When Polytoken may send isolated background prompt-cache refresh requests for conversations whose model has a cache-warming interval. when_waiting (the default) refreshes only while the conversation owns a running or queued background job; always also refreshes while the conversation is otherwise idle; never is a global off-switch that stops every refresh request. Refreshes are extra inference requests, so this key is user/global-only; a project config cannot set it.
cache_warming_refresh_limit_enabled	boolean	Enables the per-conversation refresh limit and immediate cache-miss stop for background prompt-cache refreshes. This user/global-only setting defaults to on; a project config cannot change it.
cache_warming_max_refreshes	integer	Maximum successful cache refreshes without another ordinary provider attempt in a main conversation. The built-in value is 3, and this user/global-only setting must be at least 1.
cache_warming_max_refreshes_subagent	integer	Maximum successful cache refreshes without another ordinary provider attempt in a subagent conversation. The built-in value is 1, and this user/global-only setting must be at least 1.

daemon.logging

Name	Type	Description
provider_autopsy	boolean	When on, saves a redacted report for each provider failure, without the request or response contents. Off by default.
provider_request_diagnostics	boolean	When on, Polytoken collects detailed redacted size and structure information for every provider request, including successful ones. Off by default because the breakdown adds preparation work to each request. Provider autopsy is independent of this key and still gathers what failure reports need.
persist_system_prompts	boolean	When on, Polytoken saves each composed provider system prompt in the session’s diagnostic sidecar directory. The files help you inspect prompt changes after a run and remain disabled by default.

daemon.web

Name	Type	Description
http_proxy	string	Proxy URL for the plain-HTTP requests the built-in web tools make.
https_proxy	string	Proxy URL for the HTTPS requests the built-in web tools make.
web_fetch_disallow_http	boolean	When on, blocks web_fetch from following plain-HTTP URLs except for localhost and loopback addresses.

daemon.tls

Name	Type	Description
trust_store	string	Path to a PEM file holding one or more CA certificates Polytoken should trust in addition to the certificates it already trusts. For outbound HTTPS, Polytoken verifies certificates against the operating system’s trust facilities: on macOS the Keychain, on Linux the system CA bundle plus the file named by the SSL_CERT_FILE environment variable when that variable is set. daemon.tls.trust_store adds the certificates in this file on top, so the usual roots stay trusted. Use this to inspect Polytoken’s own traffic with an HTTPS interception proxy such as mitmproxy, Charles, or Burp Suite: point this at the proxy’s CA certificate so Polytoken accepts the proxy’s man-in-the-middle certificate instead of failing verification. The file is a PEM bundle: one or more base64-encoded CA certificates, each wrapped in -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- markers. A single CA (for example mitmproxy’s mitmproxy-ca-cert.pem) or a concatenated bundle of several CAs both work. Relative paths resolve against the directory Polytoken was started in (the daemon working directory, normally the project root). Absolute paths are used as given. Omit this key to trust the operating system’s certificates only. On Linux, an SSL_CERT_FILE that points at a file Polytoken cannot load is reported as a startup error, because setting the variable is an explicit choice. On macOS the variable is not read: the Keychain is the trust source, and daemon.tls.trust_store is the file-based option. Applies to daemon-owned outbound HTTPS only: model provider requests, the built-in web_fetch and web_search tools, and the OpenAI Codex login refresh client. It does not apply to standalone polytoken auth or configurator flows run from the terminal. A path that cannot be read or parsed is a hard error at startup and on reload, so a missing or invalid file is never silently ignored.

daemon.system_reminders

Name	Type	Description
disabled	string list	Built-in system reminders Polytoken should not add to a session. Polytoken flags unknown or malformed names as config errors.

daemon.retry

Name	Type	Description
max_retries	integer	Maximum number of retry attempts for transient provider errors that use computed backoff or a provider-supplied retry-after hint. The default is 20. Set daemon.retry.max_retries to 0 to disable all provider retries. Positive values do not change the no-hint rate-limit policy, which uses a six-step ladder followed by jittered 20-minute waits until its five-hour window closes.
base_delay_ms	integer	Base delay in milliseconds for computed exponential backoff. The default is 5000 milliseconds, with equal random jitter applied to each computed wait. No-hint rate limits use their six-step ladder and jittered 20-minute waits instead.
max_computed_delay_ms	integer	Maximum computed delay in milliseconds. The default is 14,400,000 milliseconds, or four hours. This cap applies to computed exponential waits, not provider-hinted Retry-After values or the no-hint rate-limit ladder and five-hour window policy.

daemon.goal_driver

Name	Type	Description
plan_handoff_activate_goal	boolean	When on, a plan handoff automatically activates goal mode. When off, a plan handoff does not activate goal mode unless you enable it here.
agent_goal_auto_accept	boolean	When on, Polytoken accepts goals the model proposes without asking you to confirm each one. When off, goals the model proposes require your approval before they take effect.
max_continuations_per_goal	integer	Maximum automatic continuations Polytoken may run for one active goal before it stops scheduling follow-up turns for that goal. Set this to 0 to disable automatic goal continuation while keeping Goal Driver metadata and tools available.

daemon.lsp

Name	Type	Description
enabled	boolean	Whether lsp is available to the model. Defaults to true.
servers.<name>.command	string	Executable to start. A configured command must not be empty.
servers.<name>.args	string list	Arguments passed to the executable.
servers.<name>.settings	map	JSON settings sent to the language server.
servers.<name>.disabled	boolean	Prevents this server from being selected or started.
servers.<name>.language_id	string	Language identifier used when opening a document.
servers.<name>.file_types	string list	File extensions routed to this server.
servers.<name>.root_markers	string list	Project-root marker files used during server detection.
servers.<name>.init_options		JSON initialization options sent during startup.
servers.<name>.is_linter	boolean	Routes this server only for diagnostics.
idle_timeout_secs	integer	Seconds of inactivity before Polytoken retires an idle language server. Omit this key to keep language servers alive until the session ends. Session-scoped by design: the value takes effect at daemon start (when the session pool is created); /reload changes do not re-derive it mid-session.

daemon.file_catalog

Name	Type	Description
max_files	integer	Maximum number of entries the recursive catalog walk collects before stopping. Applies only outside source-controlled repositories.
max_duration_ms	integer	Maximum wall-clock milliseconds the recursive catalog walk may spend before stopping. Applies only outside source-controlled repositories.
exclude_generated	boolean	When on (default), Polytoken prunes generated build-output trees (node_modules, bazel-out, bazel-bin, bazel-testlogs, and any bazel-* directory) from the recursive catalog in all modes, including show-ignored mode.
cache_ttl_secs	integer	How long (in seconds) the daemon serves a cached file catalog before rebuilding it. The cache is also invalidated when a file-mutating tool completes.

daemon.tool_flow

Name	Type	Description
mcp_tools_deny	string list	Tool names matching these shell-style patterns cannot be called from a tool flow. The deny list takes precedence over a flow’s requested tools.
max_timeout_seconds	integer	Maximum wall-clock seconds allowed for a tool flow. Values above 24 hours use the 24-hour limit. This is the ceiling for the whole flow; the per-invocation timeout the model requests defaults to 20 minutes.
max_calls	integer	Maximum number of nested tool calls allowed in one flow. This value must be at least 1.

mcp_servers

mcp_servers.<name>

Name	Type	Description
block_list	string list	MCP tool names, in the mcp__server__tool form, that Polytoken hides from the model.
default_timeout_seconds	integer	Maximum seconds a single tool call to this server may run before Polytoken cancels it. Omit for no server-level limit; Polytoken rejects zero.
auth_key_name	string	Directory name under auth/mcp/ where Polytoken stores this server’s OAuth credentials. Omit to use the server name (the default). Two OAuth servers that should keep separate credentials can set distinct names here, for example atlassian-polytoken and atlassian-summoner. The name may contain only ASCII letters, digits, underscores, and hyphens, and must not start with an underscore or contain two underscores in a row.
default_enabled	boolean	Whether Polytoken attempts to connect to this server at startup. Set to false to keep the server available but disconnected until you enable it with /mcp. Defaults to true.
transport	one of: stdio, http
command	string	Executable to launch as the local stdio MCP server.
args	string list	Command-line arguments passed to the stdio server command.
env	map	Environment variables set on the stdio child process. The child starts with a cleared environment. These override any variables copied by pass_env.
pass_env	string list	Names of environment variables to copy from the Polytoken process into the stdio child process. Omit to use a safe default set (HOME, PATH, LANG, TMPDIR). Set to an empty list to pass nothing. Set to a list of names to pass exactly those variables. Variables in env with the same name override values passed through here.
log_stderr	boolean	When on, logs the server’s stderr to a per-server log file. On by default.
log_stdout	boolean	When on, logs the server’s stdout to a per-server log file. Off by default.
url	string	Endpoint URL of the remote streamable-HTTP MCP server.
auth	one of: none, authorization-header, oauth	How Polytoken authenticates to the remote server: none, a fixed Authorization header, or OAuth.
auth.value	string	Authorization header value to send, including any scheme prefix (for example Bearer ...).
auth.scopes	string list	OAuth scopes to request during authorization. Omit to let the server choose the defaults.
auth.registration	one of: auto, client-metadata-url, pre-registered	How Polytoken registers its OAuth client: auto, client-metadata-url, or pre-registered.
auth.registration.url	string	HTTPS URL with a non-root path that serves the client metadata document.
auth.registration.client_id	string	OAuth client identifier issued by the server.
auth.registration.client_secret	string	OAuth client secret paired with the client ID, when the server requires one.
auth.redirect	one of: ephemeral-loopback, fixed	How Polytoken handles the OAuth redirect: ephemeral-loopback or fixed.
auth.redirect.uri	string	Fixed redirect URI the authorization server returns to after consent. Must be HTTPS or a loopback HTTP address.
headers	map	Extra HTTP headers Polytoken sends with every request to the remote server. Polytoken sends User-Agent: Polytoken v<version> by default on HTTP MCP requests, and a configured User-Agent header replaces it.
reinit_on_expired_session	boolean	When on, reinitializes the HTTP session automatically when the server signals it has expired.

integrations

integrations.search

Name	Type	Description
strategy	enum	How Polytoken picks one enabled search provider per web_search call: round_robin to rotate in order, or random to select one per call.
providers.brave.enabled	boolean	Whether this provider is eligible for web_search calls.
providers.brave.key	string	API key for this provider, usually an environment reference such as ${SEARCH_API_KEY}.
providers.tavily.enabled	boolean	Whether this provider is eligible for web_search calls.
providers.tavily.key	string	API key for this provider, usually an environment reference such as ${SEARCH_API_KEY}.
providers.exa.enabled	boolean	Whether this provider is eligible for web_search calls.
providers.exa.key	string	API key for this provider, usually an environment reference such as ${SEARCH_API_KEY}.
providers.kagi.enabled	boolean	Whether this provider is eligible for web_search calls.
providers.kagi.key	string	API key for this provider, usually an environment reference such as ${SEARCH_API_KEY}.
providers.parallel.enabled	boolean	Whether this provider is eligible for web_search calls.
providers.parallel.key	string	API key for this provider, usually an environment reference such as ${SEARCH_API_KEY}.
providers.you.enabled	boolean	Whether this provider is eligible for web_search calls.
providers.you.key	string	API key for this provider, usually an environment reference such as ${SEARCH_API_KEY}.

tui

Name	Type	Description
theme	enum	Color palette: auto (detect from the terminal background), light, or dark.
theme-file	string	Theme file to load for the TUI. When unset, Polytoken uses the built-in default theme. Set this to a full path: use polytoken://themes/default.yaml for a built-in theme, or $USER_DIRECTORY/themes/my-theme.yaml for a user theme. Built-in theme paths must use the polytoken://themes/ namespace. Polytoken ignores trailing slashes on built-in theme paths. The $USER_DIRECTORY variable resolves to your Polytoken config directory and supports env-substitution syntax.
alt-screen	enum	Alternate-screen policy: auto (render inline under a terminal multiplexer, alternate screen otherwise), always, or never.
confirm-quit	boolean	Whether Polytoken asks before quitting. When unset, Polytoken follows the per-machine preference, and asks if no preference is set.
density	enum	Card spacing: standard (the default) or compact.
show-all-thinking-blocks	boolean	When enabled, completed thinking stays in the transcript as collapsible Thought cards titled with the duration of each pass. When disabled, which is the default, the thinking display disappears after the reply text arrives.
show-system-reminders	boolean	Whether the transcript shows system-reminder cards.
render-math-as-unicode	boolean	Whether the terminal displays math between $ or $$ markers using Unicode symbols. Bracket forms such as \[…\] and \(…\) use the same rendering. Set this to false to show math as written, while unsupported math falls back to the original text. Terminal fonts vary in their coverage of Unicode math glyphs. When enabled, the conversation prompt also coaches the model to write math in forms that can render as Unicode.
prompt	map	TUI prompt settings.
navigation	map	Keyboard navigation settings.
terminal-bell	enum	Bell behavior for attention states: off, audible, or auto (the default). The bell rings when an approval or question needs your answer and when assistant work finishes with control returned to you. It stays silent while work continues automatically, including plan handoffs, follow-on turns, and queued prompts. A running background job alone does not suppress the bell; only an armed notification wake or admitted follow-on work keeps control from returning to you.
terminal-titles	boolean	Whether Polytoken updates the terminal window title while the TUI runs. The default is on. This setting is independent of the title animation.
slow-refresh	boolean	When on, the TUI redraws streaming content at most every 5 seconds instead of the default ~30 times per second. This reduces screen flashing on e-ink displays during active assistant turns. Typing, scrolling, and resizing stay immediate.
expand-file-edit-cards	boolean	When on, file write and edit tool-call cards (file_write, file_edit_search_replace, file_edit_hashline, patch_edit) start expanded in the conversation transcript so you can see the full diff or content without clicking. You can still collapse any card and it stays collapsed. On by default.
show-ignored-files-in-picker	boolean	Whether the reference (@) file picker shows files matched by .gitignore, .claudeignore, or .polytokenignore when it opens. Off by default. You can toggle this at any time during a session with Shift+Tab inside the @ typeahead; this setting controls only the starting state.
status-line	array	Ordered list of modules shown in the status line. The list replaces the built-in default, which shows every module in this order: cwd, source-control, facet, model, permissions, context-usage. Set this key in your user config; a project config cannot change it.

tui.help

Name	Type	Description
default-tier	enum	Starting scope of the help overlay when opened: overview (the default), navigation, or advanced.

tui.sidebar

Name	Type	Description
side	enum	Which side the sidebar appears on: left or right (the default).
default-state	enum	Initial sidebar state: open (the default) or collapsed. Polytoken still collapses it automatically on narrow terminals.
collapse-threshold	integer	Viewport column width below which Polytoken switches to mini mode, retracting the sidebar into a floating overlay.
width	integer	Column width of the sidebar. Polytoken keeps it between 30 and 60.

tui.mouse

Name	Type	Description
enabled	boolean	Whether mouse capture and mouse-driven interactions are on. On by default.

tui.keyboard

Name	Type	Description
commands	map	Key chord overrides keyed by command id. A value may be one chord string or a list of chord strings. Omit a command to use its built-in default, or set it to an empty list to disable that command. Duplicate chords are allowed; the active TUI context and command priority decide which action runs first.

tui.editor

Name	Type	Description
command	string	External editor command to launch. When unset, Polytoken picks an editor automatically.

tui.paste

Name	Type	Description
collapse-threshold	integer	Paste size above which pasted content collapses into a sidecar preview instead of rendering inline.

tui.history

Name	Type	Description
persist	boolean	Whether Polytoken saves prompt history under the project .polytoken directory. On by default.
max-entries	integer	Maximum number of prompt history entries retained per input kind (agent prompt, command mode, slash command).
input-history-mode	enum	Whether Up and Down arrow history navigation is separated by input kind or unified across all kinds.

tui.copy

Name	Type	Description
size-cap	integer	Maximum byte size of a single clipboard copy.

tui.animations

Name	Type	Description
enabled	boolean	Whether animations run at all. On by default.
terminal-title	boolean	Whether the terminal title animates during an assistant turn. On by default.

tui.status-line

Name	Type	Description
kind	enum	Which module to render: cwd, source-control, facet, model, permissions, or context-usage. The source-control module shows the current branch label. For Git repositories, the label turns yellow when the working tree has uncommitted changes, and arrows indicate how many commits the local branch is ahead (↑) or behind (↓) its tracked upstream branch.
args	map	Reserved per-module arguments for the status-line module.

version

Config schema version. Polytoken writes 4; older configs without this key are upgraded when loaded, and version 3 defaults tier selections move into reserved modelgroups entries.

config_command_substitution

When on, Polytoken resolves $(command) and ${VAR:-command} substitutions in config values by running each command with /bin/sh -c. Commands run when config loads, when the configurator checks a provider connection before offering its models, and when the model list of a provider that publishes one live is fetched. Only your user/global config can turn this on; values in a project config never run commands. Off by default.

modelgroups

Ordered model groups provide reusable sequential failover routes. Each value is one concrete model selector or a non-empty ordered list of selectors and group references. A group reference is a name with one of four prefixes: @modelgroup:<name>, @mg:<name>, modelgroup:<name>, or mg:<name>. A bare group name never resolves as a group. Group entries preserve duplicates and explicit effort or request-option assignments.

Model groups reverse the usual configuration precedence: user/global definitions replace project definitions, and project definitions replace shipped ones. Each winning group value replaces the complete lower-priority value. A tier is a model size class: full for the main conversation model, mini for fast auxiliary work, nano for the cheapest background tasks. Reserved polytoken: groups ship built in. polytoken:default_model_full, polytoken:default_model_mini, and polytoken:default_model_nano hold each tier’s selection; when a tier has no authored selection, the mini tier resolves to the full tier’s selection, and the nano tier resolves to the mini tier’s. polytoken:general-purpose-mini and polytoken:researcher resolve to the mini tier; polytoken:general-purpose, polytoken:plan_reviewer, polytoken:execute, polytoken:orchestrate, and polytoken:plan resolve to the full tier. Authoring a reserved name replaces the shipped value.

active_session

Name	Type	Description
default_facet	string	Facet Polytoken starts in for a new interactive session, such as plan or execute. Polytoken records the facet a session started in with the session and restores that facet when you resume, even if you later change this setting. Falls back to execute when unset.
default_exec_facet	string	Facet Polytoken starts in for a non-interactive polytoken exec run. Falls back to execute when unset.

agent_behavior

agent_behavior.shell

Name	Type	Description
command	enum	Shell Polytoken uses to run shell tool calls.
init_script	string	Project-relative script Polytoken sources once before the first shell tool call, so its environment changes apply to later shell calls.

permissions

Protects secrets the model might otherwise read or repeat. permissions.secret_words lists values Polytoken blocks from environment exposure and redacts from tool output, and permissions.secret_files marks files Polytoken asks before reading and redacts from search results.

This block is separate from the permissions rule file, which controls the per-tool allow, ask, and deny rules.

Name	Type	Description
secret_words	string list	Values Polytoken blocks from environment exposure and redacts from tool output.
secret_files	string list	Files Polytoken asks before reading and redacts from search results.

notifications

Name	Type	Description
trigger_turn	boolean	Whether Polytoken starts a new turn when a notification arrives, instead of waiting for your next prompt. Reserved; Polytoken does not act on this setting.
trigger_types	string list	Notification types that should start a turn when trigger_turn is on. Reserved; Polytoken does not act on this setting.
auto_drain_notifications	boolean	Whether Polytoken folds each notification into the session history as it arrives, so the model sees it without a manual step. On by default.

default_permission_matcher

Selects the strategy Polytoken uses to decide whether a tool call is allowed when no other matcher applies. The strategies are standard (apply your allow, ask, and deny rules), bypass (allow every call without asking), bypass_plus (allow every call except those your deny rules block), and autonomous (let a classifier decide which calls are safe to run without prompting you). Omit the key to use the standard strategy.

autonomous_permission_matcher

Tunes the autonomous permission classifier, which decides whether a tool call is safe to run without asking you. autonomous_permission_matcher.classifier_model names the model that judges each call, classifier_rules gives it free-form guidance, and max_consecutive_denials caps how many denials the classifier can return in a row before Polytoken escalates to you. This block takes effect only when the autonomous strategy is active.

Name	Type	Description
classifier_model	string	Model that judges whether each tool call is safe to run without asking you.
classifier_rules	string	Free-form guidance the classifier applies when judging tool calls.
max_consecutive_denials	integer	Number of denials the classifier may return in a row before Polytoken escalates to you.

plugins

Configuration values for extensions, keyed by extension name. Polytoken passes each value to the matching extension and does not interpret the contents itself.

subagents

Sets the source for a named subagent, overriding auto-discovery. A subagent is a delegate Polytoken spawns to run a bounded task in its own context. Each entry’s source is a shipped polytoken:// reference or a project-relative file path that stays within the project.

Explicit sources override the built-in subagents and any files Polytoken discovers in .polytoken/subagents/.

subagents.<name>

Name	Type	Description
source	string	Definition source for this facet or subagent: a shipped polytoken:// reference, or a project-relative file path that stays within the project.

exec

Limits and stall handling for non-interactive polytoken exec runs.

Name	Type	Description
max_turn_wall_secs	integer	Maximum wall-clock seconds Polytoken lets the model turns of one polytoken exec run take. The budget covers the initial response and any follow-up turns in the same run. When the budget runs out, Polytoken stops the run, prints a message on stderr naming the limit, and exits with a failure code. Omit to use the built-in default. Set to zero to disable the limit.
provider_stream_idle_timeout_secs	integer	Seconds Polytoken waits for the next chunk from a provider stream during polytoken exec before treating the stream as stalled, collating the partial content, and retrying the request. Overrides daemon.provider_stream_idle_timeout_secs for exec runs only. When omitted, polytoken exec uses a smaller built-in default than interactive sessions because no person is watching the run. The setting applies to the main session stream of the exec run; subagent streams use the standard default. Polytoken treats zero as unset.

data

Crash-reporting and diagnostic data policy. This block is global-only: a project config may not set or erase any key inside it. The data.automatic_crash_reporting key controls whether Polytoken sends automatic crash reports.

Name	Type	Description
automatic_crash_reporting	boolean	Controls whether Polytoken sends automatic crash reports when the process exits unexpectedly. On by default once your user/global config loads successfully. Set to false to opt out. If your global config is missing, unreadable, or malformed, crash reporting stays off. Project configs may not set this key.

updates

Self-updater check behavior and release channel. This block is global-only: a project config may not set or erase any key inside it. The updates.automatic_check key controls whether Polytoken checks for available updates at launch. The updates.channel key selects which release channel to track.

Name	Type	Description
automatic_check	boolean	Whether Polytoken checks for available updates at launch. On by default. Set to false to disable the automatic launch-time check; polytoken update still works manually regardless of this setting. Project configs may not set this key.
channel	one of: latest, stable	Which release channel to track for updates. Defaults to latest, which resolves the newest published release. Set to stable to skip unstable pre-releases. Project configs may not set this key.

telemetry

OpenTelemetry trace export. This block is global-only: a project config may not set or erase any key inside it. When this block is absent, trace export is disabled and Polytoken sends no OTLP requests. Corresponding OTEL_* environment variables supersede values in this block, but do not enable export without it.

Name	Type	Description
protocol	one of: http/protobuf, grpc	The transport protocol for trace data. Set to http/protobuf for OTLP/HTTP or grpc for OTLP/gRPC. Superseded by OTEL_EXPORTER_OTLP_TRACES_PROTOCOL or OTEL_EXPORTER_OTLP_PROTOCOL.
endpoint	string	The collector endpoint. For http/protobuf, Polytoken expects a base URI such as http://localhost:4318 and appends /v1/traces automatically. For grpc, Polytoken expects a base URI such as http://localhost:4317 and uses it as the gRPC authority. The endpoint must not contain a path (other than a single trailing slash), query parameters, fragments, or userinfo. Superseded by OTEL_EXPORTER_OTLP_TRACES_ENDPOINT or OTEL_EXPORTER_OTLP_ENDPOINT.
headers	map	Custom headers to send with each trace export request. Keys and values support environment-variable substitution (for example key = "${AUTH_TOKEN}"). Polytoken treats both keys and values as secrets and never writes them to diagnostics, logs, or spans. Superseded by OTEL_EXPORTER_OTLP_TRACES_HEADERS or OTEL_EXPORTER_OTLP_HEADERS.
service_name	string	The service name reported in trace resource attributes. Defaults to polytoken when not set. Polytoken distinguishes daemon and exec modes with a separate attribute rather than changing the service name. Superseded by OTEL_SERVICE_NAME or the service.name key in OTEL_RESOURCE_ATTRIBUTES.

TUI keyboard commands

Each command ID below is a key you can set under tui.keyboard.commands. The value is a key chord string (such as "ctrl+g") or a list of chord strings (such as ["ctrl+shift+b", "ctrl+f1"]). An empty list disables that command. Unknown command IDs are rejected. Chords that appear in more than one command are resolved by the active context.

Separators are flexible: ctrl-shift-q and ctrl+shift+q are equivalent. The + and - keys themselves use the names Plus and Minus when you need to bind them (for example, ctrl+shift+plus). On a US keyboard, the physical +/= key sends = with Shift, so ctrl+shift+plus may arrive as Ctrl+Shift+Equal depending on your terminal.

Not all key combinations survive SSH or certain terminal emulators. If a chord does not seem to work, type /inputdebug in the prompt to open a diagnostic overlay that shows the exact keycodes the TUI receives.

Command ID	Default	Action	Scopes
open-help	Ctrl+/, F1	Open this command reference from any normal input context.	Global
end-session	Ctrl+C	Press twice before the flash expires to terminate the daemon session.	Global
detach-session	Ctrl+D	Leave the daemon running and close only this TUI.	Global
interrogative-yes	Y	Accept a yes/no interrogative.	Interrogative
interrogative-no	N	Reject a yes/no interrogative.	Interrogative
interrogative-cancel	Esc	Cancel the pending interrogative.	Interrogative
interrogative-submit	Enter	Submit the pending interrogative answer.	Interrogative
interrogative-next	Enter	Advance to the next ask-user-question item.	Interrogative
interrogative-previous-question-when-focused	Ctrl+Left, Ctrl+Shift+Left	Move to the previous ask-user-question item while the text editor is focused.	Interrogative
interrogative-next-question-when-focused	Ctrl+Right, Ctrl+Shift+Right	Move to the next ask-user-question item while the text editor is focused.	Interrogative
interrogative-toggle	Space	Toggle the selected option or custom-answer checkbox.	Interrogative
interrogative-edit-custom	Tab	Move focus into or out of the custom-answer editor.	Interrogative
interrogative-copy	Ctrl+Y	Copy the plan or question explanation to clipboard.	Interrogative
interrogative-monitor-mode-previous	Left, [	Cycle the permission monitor mode selector backward in a permission popup.	Interrogative
interrogative-monitor-mode-next	Right, ]	Cycle the permission monitor mode selector forward in a permission popup.	Interrogative
interrogative-toggle-context	Ctrl+Shift+B, Ctrl+F1	Collapse or expand the ask_user_question context area.	Interrogative
toggle-sidebar	Ctrl+Shift+B, Ctrl+F1	Open or collapse the sidebar.	Sidebar
toggle-sidebar-flags	Ctrl+F2	Open or close the flagged files pane.	Sidebar
toggle-sidebar-jobs	Ctrl+F3	Open or close the async jobs pane.	Sidebar
toggle-sidebar-todos	Ctrl+F4	Open or close the todos pane.	Sidebar
submit-prompt	Enter	Send the current prompt to the attached daemon session.	Prompt
insert-newline	Shift+Enter, Alt+Enter	Add a newline without submitting the prompt.	Prompt
open-editor	Ctrl+G	Open the prompt in your configured editor, then restore it.	Prompt
enter-navigation	Ctrl+Up	Move focus from the prompt into conversation navigation.	Prompt
copy-prompt	Ctrl+Y	Copy the complete prompt draft.	Prompt
cut-prompt	Ctrl+Shift+Y	Copy the prompt text and clear the buffer so it can be restored later.	Prompt
local-paste	Ctrl+V	Paste the most recently copied or cut prompt text back into the prompt.	Prompt
paste-image	Ctrl+Alt+V	Add an image from the system clipboard to the next prompt or the feedback form.	Prompt, Feedback
pasted-image-remove	Ctrl+Alt+X	Clear all pending clipboard images from the next prompt or the feedback form.	Prompt, Feedback
history-search	Ctrl+R	Open fuzzy search across persisted prompt history.	Prompt
prompt-permission-typeahead	Ctrl+Shift+P	Open or cycle the permission-monitor argument typeahead.	Prompt
send-to-background	Ctrl+B	Send the currently running shell tool to the background.	Prompt
model-reasoning-previous	[	Select the previous reasoning level for the highlighted model.	Prompt
model-reasoning-next	]	Select the next reasoning level for the highlighted model.	Prompt
copy-card	Ctrl+Y	Copy the focused card’s raw backing content.	Conversation
rewind-card	Ctrl+R	Open rewind confirmation for the focused card (prompt, compaction, context clear, or facet switch).	Conversation
exit-navigation	Esc	Return focus from conversation navigation to the prompt.	Conversation
help-close	Esc	Close help and restore the previous floating window.	Help
palette-accept	Tab, Enter	Complete the selected result in the prompt.	Slash palette, Reference picker
history-accept	Enter	Replace the draft with the selected history item.	History search
palette-cancel	Esc	Close the active typeahead or search popup.	Slash palette, Reference picker, History search
dialog-accept	Enter	Activate the selected dialog option.	Rewind confirmation
dialog-number	1-9	Activate a visible dialog option by number.	Rewind confirmation
dialog-close	Esc	Close the dialog without taking its primary action.	Rewind confirmation
todo-viewer-delete	Delete	Open delete confirmation for the selected todo.	Todo viewer
todo-close	Esc	Close todo details and return to the prompt.	Todo viewer
license-close	Esc	Close the license viewer and return to the prompt.	License viewer
prompt-facet-typeahead	Shift+Tab	Open or cycle the internal facet argument typeahead.	Prompt