Expand description
Configuration loading and defaults for codewhale.
Structs§
- Account
Model Access - Process-only account auth transform. Shared by Config clones so logout and expiry affect future request resolution without rewriting provider config. Running turns retain their materialized client; immediate revocation of that credential remains the account service’s responsibility.
- Approval
Config - Approval-card presentation (
[approval]table in config.toml). Approval policy stays the top-levelapproval_policykey; this table only governs how the card is presented once a prompt is already required. - Auto
Config [auto]table — knobs for the--model auto//model autorouter.- Auto
Review Config - Auto
Review Rule Config - Auto
Router Config - Explicit classifier route for Auto model mode (
[auto.router]). - Bundled
Skills Config - Cloud
Facts Config - Cloud facts overlay (
[cloud_facts]table in config.toml). Off by default; seedocs/CLOUD_FACTS.md. Env:CODEWHALE_CLOUD_FACTS=1|0overridesenabled,CODEWHALE_DISABLE_CLOUD_FACTS=1is a hard kill switch. - Compaction
Settings - Compaction summarizer tuning (
[compaction], #5956). - Config
- Resolved CLI configuration, including defaults and environment overrides.
- Context
Config - Context management configuration.
- Goal
Config - Persistent-goal loop controls (
[goal]table in config.toml, #5052). - Memory
Config - Mini
Window Config - Layout preferences for the pinned (always-on-top) mini-window mode.
- Model
Alias Deprecation - Upstream retirement metadata for a model alias that remains compatible.
- Provider
Config - Provider
Identity - Exact, non-secret provider identity resolved from live configuration.
- Providers
Config - Rate
Limit Retry Policy - Independent recovery limits for HTTP 429; other transport errors keep their policy.
- Reasoning
Only Config - Reasoning-only recovery controls (
[reasoning_only]table in config.toml). When the model returns only hidden reasoning (thinking) without any answer text or tool call, the engine can re-request the answer automatically. - Retry
Config - Raw retry configuration loaded from config files.
- Retry
Policy - Resolved retry policy with defaults applied.
- Route
Provenance - UI configuration loaded from config files.
- Runtime
ApiConfig [runtime_api]table — knobs for the local HTTP/SSE daemon.- Search
Config - Web search provider configuration (
[search]table in config.toml). - Search
Provider Resolution - Skills
Config [skills]table — discovery, ambient index and installer configuration.- Snapshots
Config - Workspace side-git snapshot configuration (#137).
- Speech
Config - Xiaomi MiMo speech/TTS output configuration.
- Stream
Config - Canonical model-stream and transport settings. The existing
Configaccessors own resolution;[tui]spellings remain read-only compatibility. Transport changes apply to newly constructed clients, not active requests. - Subagent
Model Override - One role override carried through Config, Engine, and child admission. Provider identity is retained until the existing route resolver binds it.
- Subagent
Provider Config - Provider-specific sub-agent limit overrides.
- Subagent
Role Config - One authored role pin. This new field accepts an explicit
provider/modeldeclaration, or a bare model on the session provider. Legacy model inputs retain their opaque provider-owned ids, including any slashes. - Subagents
Config - Fleet-role model overrides for delegated workers. Canonical keys in
modelsareworker,scout,planner,reviewer,builder,verifier, andcustom. Legacy sub-agent type names remain accepted for v0.9.x compatibility. Explicit manual pins are authoritative at admission. - Tools
Config - Model-visible tool catalog controls (
[tools]table in config.toml). - Transcript
Config - Transcript rendering controls (
[transcript]table in config.toml). - TuiConfig
- Update
Config - Startup update-check configuration (
[update]table in config.toml). - Vision
Model Config - Vision model configuration for the
image_analyzetool. Uses an OpenAI-compatible vision model API.
Enums§
- Approval
Default Selection - Which approval option a freshly rendered approval card highlights.
- Approval
Policy Control - The highest-precedence source that can currently own approval policy.
- Auto
Router Kind [auto.router] kind(#6525).- Base
UrlEnv Receipt - What the environment layer decided about the generic
CODEWHALE_BASE_URL/DEEPSEEK_BASE_URLoverride. - Bundled
Skills Install - Chrome
RowPreset - How much of one bottom-chrome row to paint (#5950). One value for each
of the two rows under the composer —
TuiConfig::posture_barandTuiConfig::metrics_line— so a small tmux pane can give one or both rows back to the transcript without touchingstatus_items. - Config
Environment Policy - Controls whether configuration loading may copy secret-bearing environment values into the in-memory configuration.
- Memory
Backend - User-level memory configuration (#489).
- RawProse
Measure transcript.prose_measureexactly as written inconfig.toml.- Safe
Config Diagnostic - Configuration errors whose text is safe to show in diagnostics such as
codewhale doctor. Everything else stays suppressed there because parse errors and credential fields can echo secret material. - Saved
Credential - Where a saved credential ended up. Returned by
save_api_keyso the caller can show a confirmation message without leaking the key. - Search
Provider - Search provider enumeration — selects the first backend
web_searchuses. API-backed providers may visibly degrade through DuckDuckGo → Bing after runtime failure or an empty result. Configuration and network-policy errors fail closed without crossing providers. - Search
Provider Source - Shell
Access Control - Highest-precedence source that owns the interactive shell availability switch. Project/profile/environment/managed constraints are intentionally read-only from the root settings editor.
- Status
Item - One configurable bottom-chrome item.
- Tool
Override - How a user wants to disable a tool or supply a script / command tool.
Only
Disabledmay target a built-in; seeToolsConfig::overrides.
Constants§
- COMPACTION_
SUMMARY_ INSTRUCTIONS_ MAX_ CHARS - Maximum characters of
[compaction] summary_instructionsthat are appended to the summarizer prompt. Longer values are truncated (with a warning) rather than rejected: a long standing instruction should not fail the compaction pass that keeps the session alive. - DEEPSEEK_
ALIAS_ RETIREMENT_ DATE - DEEPSEEK_
ALIAS_ RETIREMENT_ UTC - DEFAULT_
AUTO_ ROUTER_ MIN_ CONFIDENCE - Default
[auto.router] min_confidencefor decision routers: TypeSafe’s “below 0.5, don’t act” band (for two options, the chosen tier’s probability must reach 0.75). - DEFAULT_
COMPACTION_ RETAINED_ USER_ MESSAGE_ TOKENS - Default verbatim retention budget for recent plain user messages in the compaction replacement history (Codex parity). Unset config keeps this.
- DEFAULT_
CONNECT_ TIMEOUT_ SECS - Default TCP/TLS connect timeout for the model HTTP client, in seconds.
- DEFAULT_
MAX_ SUBAGENTS - Temporary high-throughput default while the shared-context cutover makes agent fanout cheap. This should eventually be governed by API/backpressure budgets rather than memory-driven count throttles.
- DEFAULT_
REASONING_ ONLY_ REPROMPTS - Default maximum number of automatic re-requests when a reasoning model returns only hidden thinking without any answer text or tool call.
- DEFAULT_
REASONING_ ONLY_ REPROMPT_ MESSAGE - Nudge sent with a recovery request after a bare clean-stop retry, or
immediately on an opted-in output-limit retry. Configurable via
reprompt_message. - DEFAULT_
STREAM_ CHUNK_ TIMEOUT_ SECS - Default per-SSE-chunk idle timeout, in seconds.
- DEFAULT_
SUBAGENT_ API_ TIMEOUT_ SECS - Default per-step DeepSeek API timeout for sub-agent requests, in seconds.
Raised from the legacy 120s: a live-but-slow reasoning call routinely
outlasts two minutes, and a timed-out attempt is now retried with backoff
before the step interrupts, so the default should only trip on genuinely
stuck calls (FINISH-0.9.4 entry #40). Applies when
[subagents] api_timeout_secsis unset (#1806, #1808). - DEFAULT_
SUBAGENT_ HEARTBEAT_ TIMEOUT_ SECS - Default wall-clock interval without manager-visible sub-agent progress before a running child can be auto-cancelled to release its slot (#2614).
- DEFAULT_
SUBAGENT_ TOOL_ TIMEOUT_ SECS - Default wall-clock budget for a single sub-agent tool execution, in
seconds. This is the single source of truth for the default:
tools::subagent::DEFAULT_TOOL_TIMEOUTderives from it, so the heartbeat floor below and the timeout actually applied to a running tool can never drift apart. - DEFAULT_
ZAI_ PROVIDER_ MAX_ CONCURRENCY - HOOKS_
RECEIPT_ KEY - Project file approvals live only in user-owned config, never in the repo.
- KIMI_
CODE_ MEMBERSHIP_ MODELS - The Kimi Code membership roster, as one fact.
- KIMI_
CODE_ MEMBERSHIP_ PLAN_ CONSOLE_ URL - MAX_
AUTO_ ROUTER_ TIMEOUT_ SECS - Upper clamp for a configured classifier timeout: a hung local router must not stall an Auto turn forever.
- MAX_
COMPACTION_ RETAINED_ USER_ MESSAGE_ TOKENS - Upper clamp: above this the “compacted” history is large enough to re-trigger compaction on the next turn.
- MAX_
CONNECT_ TIMEOUT_ SECS - Maximum accepted connect timeout.
- MAX_
PROVIDER_ REQUEST_ CONCURRENCY - MAX_
STREAM_ CHUNK_ TIMEOUT_ SECS - Maximum accepted stream chunk timeout.
- MAX_
SUBAGENTS - User-configurable ceiling for concurrent sub-agent execution. Keep this above the default so operators can opt into larger API-bound fanout without code changes while the full resource budget gate lands.
- MAX_
SUBAGENT_ ADMISSION - Upper bound for queued + running sub-agent admissions. This is deliberately higher than the instantaneous concurrency cap so Workflow-style fanout can opt into large bounded populations without unbounded queue growth.
- MAX_
SUBAGENT_ API_ TIMEOUT_ SECS - Maximum accepted
[subagents] api_timeout_secs(60 minutes). The cap keeps a misconfigured per-step timeout from masking real model/network hangs forever. - MAX_
SUBAGENT_ HEARTBEAT_ TIMEOUT_ SECS - Maximum accepted
[subagents] heartbeat_timeout_secs(1 hour). - MCP_
RECEIPT_ KEY - MIN_
COMPACTION_ RETAINED_ USER_ MESSAGE_ TOKENS - Lower clamp: below this the replacement history stops carrying a usable amount of the user’s own words.
- MIN_
CONNECT_ TIMEOUT_ SECS - Minimum accepted connect timeout.
- MIN_
STREAM_ CHUNK_ TIMEOUT_ SECS - Minimum accepted stream chunk timeout.
- MIN_
SUBAGENT_ API_ TIMEOUT_ SECS - Minimum accepted
[subagents] api_timeout_secs. Anything lower (including0, which would otherwise produce an immediate timeout footgun) clamps up to this value before the runtime sees it. - MIN_
SUBAGENT_ HEARTBEAT_ TIMEOUT_ SECS - Minimum accepted
[subagents] heartbeat_timeout_secs. - OPENAI_
CODEX_ EFFECTIVE_ CONTEXT_ WINDOW_ TOKENS - Conservative offline floor for an OAuth model absent from a fresh Codex roster. Fresh account-scoped cache metadata overrides this in route_runtime.
- XAI_
OAUTH_ KEY_ SOURCE - Key-source label the resolver gives a key minted by xAI OAuth (owned sign-in or consented Grok CLI import), named in authentication errors.
- XIAOMI_
MIMO_ PAY_ AS_ YOU_ GO_ BASE_ URL - XIAOMI_
MIMO_ TOKEN_ PLAN_ AMS_ BASE_ URL - XIAOMI_
MIMO_ TOKEN_ PLAN_ CN_ BASE_ URL - XIAOMI_
MIMO_ TOKEN_ PLAN_ SGP_ BASE_ URL
Traits§
Functions§
- active_
provider_ env_ api_ key_ source - Where the active provider’s environment key comes from, in the resolver’s
env precedence (
credential_resolvesteps 4-6):--api-key, the route’sapi_key_envvariable, or the provider’s own ambient variable. Returns the place’s name only; any value read to test presence is dropped here. - active_
provider_ has_ config_ api_ key - active_
provider_ has_ env_ api_ key - active_
provider_ uses_ env_ only_ api_ key - approval_
policy_ baseline_ from_ permission_ posture - Map the saved TUI permission posture onto the approval-policy ordering used
by project config. Full Access is looser than every project policy, so its
baseline is the loosest ranked policy (
auto). - auto_
review_ action_ kind_ name - Canonical action-kind name for an
auto_reviewaction_kindspelling, including the retired narrow kinds that fold into a current class. - base_
url_ uses_ local_ host - Whether a base URL points at a loopback/unspecified host, i.e. a local
runtime rather than a hosted endpoint. Shared by the active-provider
local-base-url check above and the
/providerpicker’s custom-provider auth-optionality heuristic (#3830). - clear_
active_ provider_ api_ key - Clear only the active provider’s API key from the config file and delete
that provider’s durable secret-store slot (#5196).
Unlike
clear_api_key()which strips ALL api_key entries, this removes only the key for the specified provider section (plus a leftover legacy top-levelapi_keyfor DeepSeek or the literal custom route). - clear_
api_ key - Clear every saved API key from config-file storage AND the durable secret store.
- cli_
api_ key_ source - clipboard_
images_ dir - Resolve the directory pasted images should land in. Prefers
~/.codewhale/clipboard-images/so the path is stable across worktrees and matches the location described in user-facing docs; falls back to<workspace>/clipboard-images/if the home dir is unavailable. - configured_
model_ for_ route - credential_
config_ path - Resolve the config document for CREDENTIAL writes: api_key values,
auth_modemarkers, and oauth/external-credential pointers. - credential_
help_ for_ provider_ route - Credential help for a concrete provider route.
- credential_
secret_ store - The durable secret store for credential saves and logout-time deletes.
- deepseek_
alias_ deprecation - default_
stop_ words - ensure_
config_ file_ exists - Create an inspectable config file on first interactive launch.
- ensure_
parent_ dir - expand_
path - explicit_
cli_ api_ key_ override - explicit_
launch_ model_ override - The model this launch was explicitly asked for, if any.
- explicit_
launch_ provider_ override - The provider this launch was explicitly asked for, if any.
- home_
config_ path - The user-global config document:
$CODEWHALE_HOME/config.tomlwhen an explicit home is set, otherwise~/.codewhale/config.toml(falling back to the legacy~/.deepseek/config.tomlonly when that file already exists). - hook_
receipt_ for_ workspace - initialize_
cloud_ facts - Activate facts only at accepted inference runtime settings boundaries. Identical settings preserve the shared ticket; readers track its generation.
- is_
exact_ direct_ moonshot_ k3_ route - Whether a route is exactly Moonshot’s direct pay-as-you-go K3 route.
- is_
exact_ kimi_ code_ bare_ k3_ route - Whether a route uses plan-tier-dependent bare
k3. - is_
exact_ kimi_ code_ k3_ route - Whether a route uses either official Kimi Code K3 membership model.
- is_
exact_ known_ zai_ reasoning_ route - Whether a route is an exact first-party Z.ai model with a verified reasoning control. GLM-5.2, GLM-5.3, and GLM-5.3-Flash have tiered effort; GLM-5.1 and GLM-5-Turbo only expose the generic thinking toggle.
- is_
exact_ minimax_ anthropic_ m3_ route - Whether a route is exactly MiniMax-M3 on a first-party Anthropic-compatible Messages endpoint. The wire supports adaptive/disabled thinking, but no distinct effort tier.
- is_
exact_ minimax_ m3_ route - Whether a route is exactly MiniMax-M3 on the first-party OpenAI-compatible Chat API. Compatible gateways and the Anthropic Messages route retain their own token-limit dialects.
- is_
exact_ zai_ chat_ route - Whether a route is one of Z.ai’s exact first-party Chat endpoints.
- is_
exact_ zai_ forced_ thinking_ route - Whether a route is exactly first-party Z.ai GLM-5.3 or GLM-5.3-Flash.
- is_
exact_ zai_ tiered_ effort_ route - Whether a route is an exact first-party Z.ai model that exposes tiered
reasoning effort (
reasoning_effort: high | max) rather than only the generic thinking toggle. - is_
home_ config_ path - Compare the physical user-global document using the same parent path normalization and file-symlink rejection as ConfigStore.
- is_
kimi_ code_ membership_ model - Whether
modelis a Kimi Code membership model id. - is_
legacy_ antigravity_ identity - is_
unresolved_ local_ ollama_ model - True when
modelis the pre-refresh local-Ollama placeholder, not a tag. - is_
workspace_ trusted - legacy_
deepseek_ alias_ effort_ for_ route - Recover the behavioral intent of a retiring alias only when the selected
route is a first-party DeepSeek endpoint. Custom endpoints own both the id
and its semantics, so they deliberately return
Nonehere. - looks_
like_ tavily_ key - Tavily issues keys in the
tvly-family; the Tavily error copy already says so. Applied to generic keys only — a dedicatedTAVILY_API_KEYis honored as-is, however it is shaped. - minimax_
base_ url_ is_ supported_ direct - MiniMax’s own hosted routes, for both wire dialects.
- minimax_
m3_ route_ uses_ max_ completion_ tokens - model_
completion_ names_ for_ provider - Reviewed per-provider model id projection used only as a compatibility fallback (#4188).
- moonshot_
base_ url_ is_ exact_ direct_ platform - The exact Moonshot direct-API endpoint, normalized only for an
insignificant trailing slash. Custom gateways must retain their own wire
contract even when they expose a
kimi-k3model id. - moonshot_
base_ url_ is_ exact_ kimi_ code - The Kimi Code API endpoint, normalized only for insignificant trailing
slashes. This must stay stricter than
moonshot_base_url_uses_kimi_code: route-specific K3 capability and request shaping are not safe for arbitrary Kimi-hosted paths. - moonshot_
k3_ route_ display_ name - Short route label for header/diagnostics without credentials (#4687).
- needs_
trust - normalize_
base_ url - normalize_
custom_ model_ id - opencode_
go_ model_ id - owned_
skills_ dir - parse_
config_ after_ locked_ migration - Project the fresh receipt returned by the existing locked document writer. This does not reuse the caller’s diagnostic notes: a root-less document receives no missing-id provenance, and verification still compares the complete current table generation against the previously captured identity.
- parse_
config_ base - Parse one
config.toml-shaped layer (no profile applied) throughparse_config_file, so the legacy top-level keys are canonicalized. - persist_
external_ credential_ consent_ for_ at - Persist an explicitly confirmed read-only external credential grant and update the live mirror only after the comment-preserving disk mutation succeeds.
- project_
receipt_ for_ workspace - provider_
config_ key - provider_
config_ uses_ kimi_ imported_ token - provider_
env_ api_ key_ var - Name of the ambient provider variable that currently holds a non-empty key
for
provider. Presence only: the value is dropped here. - provider_
has_ balance_ api - Prepaid providers that publish a remaining-credit endpoint Codewhale can fetch. Local runtimes and invoice-only vendors stay out.
- provider_
is_ configured - Whether a provider counts as “configured” for the default
/providerand/modelmanager views (#3830). Shared by both pickers so “what shows up without browsing the full catalog” stays a single definition. Self-hosted providers (Ollama/Sglang/Vllm) reporthas_key = trueunconditionally incodewhale_tui::provider_readiness::has_api_key_forsince they don’t require auth to route to — that’s correct for routing, but wrong for “did the user set this up,” so a self-hosted provider only qualifies via an explicit[providers.<name>]entry or being active, never viahas_keyalone (otherwise every self-hosted provider type would always show up). - provider_
route_ is_ keyless_ self_ hosted - Whether this concrete route is a self-hosted endpoint whose credentials are optional by default.
- provider_
secret_ store_ api_ key - Read only the durable secret-store layer (no environment fallback).
- provider_
secret_ store_ slot - Canonical durable-credential slot shared with the CLI dispatcher.
- read_
plugin_ settings - The
[plugins]table of the user config file atpath, read on its own so an edit reaches the extension host at/plugin reloadwithout reloading the whole configuration. A missing file has no settings. Blocking. - resolve_
credential_ source - Resolve which place holds a credential for
provider, using the real process environment. - resolve_
load_ config_ path - revoke_
external_ credential_ consent_ for_ at - Revoke one provider’s external-file access without inspecting that file.
- save_
api_ key - Save the active provider’s API key.
- save_
api_ key_ for_ identity - Save an API key for the given provider identity and return where the
credential actually landed (
SavedCredential) so callers can state the true destination — the durable secret store plus credential-free config metadata, or (tests only) the plaintext config file (#5195). - save_
provider_ base_ url_ for_ identity - Persist a guided-setup endpoint choice into the provider’s own
[providers.<name>] base_url(#4526). - save_
provider_ context_ window_ for_ identity - Persist a guided-setup context-window choice without replacing the user’s surrounding TOML comments or formatting.
- save_
provider_ model_ for_ identity - Persist a guided-setup model through the same canonical route writer used by Runtime and the interactive model picker.
- save_
workspace_ hook_ receipt - save_
workspace_ project_ receipt - save_
workspace_ trust - set_
workspace_ trust - tavily_
env_ key TAVILY_API_KEY, read at request time. Deliberately never merged intoSearchConfig::api_key: that generic slot is shared by every provider, so merging would hand a Tavily key to Firecrawl (or the reverse) the moment the operator pins a different provider.- tavily_
key_ from - The key a Tavily request should send.
- validate_
auto_ review_ environment - validate_
auto_ review_ reviewer_ model - validate_
kimi_ code_ api_ model_ id - Fail closed on known-bad model/endpoint pairings (#4687).
- validate_
route - workspace_
trust_ config_ candidate_ paths
Type Aliases§
- Resolved
ApiKey (key, source label)as the active-route resolver returns it.