Skip to main content

Module config

Module config 

Source
Expand description

Configuration loading and defaults for codewhale.

Structs§

AccountModelAccess
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.
ApprovalConfig
Approval-card presentation ([approval] table in config.toml). Approval policy stays the top-level approval_policy key; this table only governs how the card is presented once a prompt is already required.
AutoConfig
[auto] table — knobs for the --model auto / /model auto router.
AutoReviewConfig
AutoReviewRuleConfig
AutoRouterConfig
Explicit classifier route for Auto model mode ([auto.router]).
BundledSkillsConfig
CloudFactsConfig
Cloud facts overlay ([cloud_facts] table in config.toml). Off by default; see docs/CLOUD_FACTS.md. Env: CODEWHALE_CLOUD_FACTS=1|0 overrides enabled, CODEWHALE_DISABLE_CLOUD_FACTS=1 is a hard kill switch.
CompactionSettings
Compaction summarizer tuning ([compaction], #5956).
Config
Resolved CLI configuration, including defaults and environment overrides.
ContextConfig
Context management configuration.
GoalConfig
Persistent-goal loop controls ([goal] table in config.toml, #5052).
MemoryConfig
MiniWindowConfig
Layout preferences for the pinned (always-on-top) mini-window mode.
ModelAliasDeprecation
Upstream retirement metadata for a model alias that remains compatible.
ProviderConfig
ProviderIdentity
Exact, non-secret provider identity resolved from live configuration.
ProvidersConfig
RateLimitRetryPolicy
Independent recovery limits for HTTP 429; other transport errors keep their policy.
ReasoningOnlyConfig
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.
RetryConfig
Raw retry configuration loaded from config files.
RetryPolicy
Resolved retry policy with defaults applied.
RouteProvenance
UI configuration loaded from config files.
RuntimeApiConfig
[runtime_api] table — knobs for the local HTTP/SSE daemon.
SearchConfig
Web search provider configuration ([search] table in config.toml).
SearchProviderResolution
SkillsConfig
[skills] table — discovery, ambient index and installer configuration.
SnapshotsConfig
Workspace side-git snapshot configuration (#137).
SpeechConfig
Xiaomi MiMo speech/TTS output configuration.
StreamConfig
Canonical model-stream and transport settings. The existing Config accessors own resolution; [tui] spellings remain read-only compatibility. Transport changes apply to newly constructed clients, not active requests.
SubagentModelOverride
One role override carried through Config, Engine, and child admission. Provider identity is retained until the existing route resolver binds it.
SubagentProviderConfig
Provider-specific sub-agent limit overrides.
SubagentRoleConfig
One authored role pin. This new field accepts an explicit provider/model declaration, or a bare model on the session provider. Legacy model inputs retain their opaque provider-owned ids, including any slashes.
SubagentsConfig
Fleet-role model overrides for delegated workers. Canonical keys in models are worker, scout, planner, reviewer, builder, verifier, and custom. Legacy sub-agent type names remain accepted for v0.9.x compatibility. Explicit manual pins are authoritative at admission.
ToolsConfig
Model-visible tool catalog controls ([tools] table in config.toml).
TranscriptConfig
Transcript rendering controls ([transcript] table in config.toml).
TuiConfig
UpdateConfig
Startup update-check configuration ([update] table in config.toml).
VisionModelConfig
Vision model configuration for the image_analyze tool. Uses an OpenAI-compatible vision model API.

Enums§

ApprovalDefaultSelection
Which approval option a freshly rendered approval card highlights.
ApprovalPolicyControl
The highest-precedence source that can currently own approval policy.
AutoRouterKind
[auto.router] kind (#6525).
BaseUrlEnvReceipt
What the environment layer decided about the generic CODEWHALE_BASE_URL / DEEPSEEK_BASE_URL override.
BundledSkillsInstall
ChromeRowPreset
How much of one bottom-chrome row to paint (#5950). One value for each of the two rows under the composer — TuiConfig::posture_bar and TuiConfig::metrics_line — so a small tmux pane can give one or both rows back to the transcript without touching status_items.
ConfigEnvironmentPolicy
Controls whether configuration loading may copy secret-bearing environment values into the in-memory configuration.
MemoryBackend
User-level memory configuration (#489).
RawProseMeasure
transcript.prose_measure exactly as written in config.toml.
SafeConfigDiagnostic
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.
SavedCredential
Where a saved credential ended up. Returned by save_api_key so the caller can show a confirmation message without leaking the key.
SearchProvider
Search provider enumeration — selects the first backend web_search uses. 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.
SearchProviderSource
ShellAccessControl
Highest-precedence source that owns the interactive shell availability switch. Project/profile/environment/managed constraints are intentionally read-only from the root settings editor.
StatusItem
One configurable bottom-chrome item.
ToolOverride
How a user wants to disable a tool or supply a script / command tool. Only Disabled may target a built-in; see ToolsConfig::overrides.

Constants§

COMPACTION_SUMMARY_INSTRUCTIONS_MAX_CHARS
Maximum characters of [compaction] summary_instructions that 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_confidence for 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_secs is 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_TIMEOUT derives 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 (including 0, 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§

ModelHttpPolicy

Functions§

active_provider_env_api_key_source
Where the active provider’s environment key comes from, in the resolver’s env precedence (credential_resolve steps 4-6): --api-key, the route’s api_key_env variable, 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_review action_kind spelling, 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 /provider picker’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-level api_key for 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_mode markers, 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.toml when an explicit home is set, otherwise ~/.codewhale/config.toml (falling back to the legacy ~/.deepseek/config.toml only 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 model is a Kimi Code membership model id.
is_legacy_antigravity_identity
is_unresolved_local_ollama_model
True when model is 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 None here.
looks_like_tavily_key
Tavily issues keys in the tvly- family; the Tavily error copy already says so. Applied to generic keys only — a dedicated TAVILY_API_KEY is 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-k3 model 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) through parse_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 /provider and /model manager 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) report has_key = true unconditionally in codewhale_tui::provider_readiness::has_api_key_for since 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 via has_key alone (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 at path, read on its own so an edit reaches the extension host at /plugin reload without 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 into SearchConfig::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§

ResolvedApiKey
(key, source label) as the active-route resolver returns it.