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.

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.
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	Codex auth profile name that supplies tokens for the device OAuth flow.
auth.profile	string	Kimi Code auth profile name that supplies tokens for the device code OAuth login flow. Use the profile name you chose when running polytoken login to authenticate with Kimi Code.
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.
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.

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. The provider-reported capability list determines eligibility for default slots, so the class override is informational for discovered models.

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: whether reasoning is off, effort-steered, or thinking-steered.
reasoning.effort_set	string	Effort family the levels belong to (for example an OpenAI reasoning effort set).
reasoning.can_disable	boolean	Whether the model can turn reasoning off.
reasoning.levels	string list	Discrete effort levels the model accepts, in provider order.
reasoning.default_level	string	Default reasoning effort when you do not name one. Must be one of levels when present.
reasoning.can_disable	boolean	Whether the model can turn thinking off.
edit_format	string	File-edit format Polytoken exposes for the model (for example a hashline or patch format); omit 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].
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, the value derives from the model’s context_window: 4 for an unknown or small window, increasing for larger windows up to 8.
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.

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.
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.
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.

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.

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 root certificates it trusts by default (its built-in root bundle). The default roots always stay enabled; the CA here is added on top. 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 only the default roots, which is the default. 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 with computed backoff or a provider-supplied retry-after hint. Set to 0 to disable all provider retries. Provider rate limits without a retry-after hint use Polytoken’s fixed six-step schedule for any positive value.
base_delay_ms	integer	Base delay in milliseconds for computed exponential backoff. Provider rate limits without a retry-after hint use a fixed 30s, 60s, 120s, 240s, 480s, 960s schedule instead.
max_computed_delay_ms	integer	Maximum computed delay in milliseconds (caps exponential backoff only, not provider-hinted Retry-After values or the fixed no-hint rate-limit schedule).

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.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.

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.
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}.

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. 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	Whether completed model thinking cards stay visible in the transcript after they finish.
show-system-reminders	boolean	Whether the transcript shows system-reminder cards.
prompt	map	TUI prompt settings.
navigation	map	Keyboard navigation settings.
terminal-bell	enum	Bell behavior for attention states: off, audible, or auto (the default, which notifies on attention).
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.

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.

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 3; older configs without this key are upgraded when loaded.

config_command_substitution

When on, Polytoken resolves $(command) and ${VAR:-command} substitutions in config values by running each command with /bin/sh -c once when it loads config. Only your user/global config can turn this on; values in a project config never run commands. Off by default.

defaults

Name	Type	Description
full	string	Name of the primary model a session uses by default. May include an effort suffix, e.g. "gpt-5.6-luna(high)", to set the default reasoning effort for this tier.
mini	string	Name of the smaller model Polytoken uses to compact context and to run the autonomous permission classifier. Falls back to full when unset. May include an effort suffix.
nano	string	Name of the smallest model class. When unset, default_model:nano falls back to mini, then full. May include an effort suffix. This is an independent tier with its own model and effort.

active_session

Name	Type	Description
default_facet	string	Facet Polytoken starts in for a new interactive session, such as plan or execute. 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.

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. All settings come exclusively from this block; ambient OTEL_* environment variables do not enable or configure export.

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.
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.
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.
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.

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-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
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, or context clear).	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
prompt-facet-typeahead	Shift+Tab	Open or cycle the internal facet argument typeahead.	Prompt