Loader for ~/.pixir/config.json (ADR 0005 ergonomics).
Parses user-global knobs, ignores invalid values with warnings (never hard-fails on a bad field), and resolves effective values with this precedence for each key:
config :pixir, :key(programmatic override)~/.pixir/config.json- built-in default
Model id keeps the Provider chain: config :pixir, :model → PIXIR_MODEL →
"model" in config.json → built-in default.
Legacy keys (model, models, context_windows) remain supported alongside the
expanded surface (permission_default, reasoning.effort, text.verbosity,
bash_timeout_ms, bash_timeout_max_ms, host_commands, max_retries,
stream_idle_timeout_ms, compaction.tail_events).
bash_timeout_max_ms is an override cap, not a way to shorten the configured
default. The effective cap is never lower than bash_timeout_ms; when config asks
for a lower cap, load/1 reports a warning and raises the effective cap so the
default bash command remains executable.
Summary
Functions
Whether model-assisted compaction is enabled (default false).
Anthropic models list from config.json only, or nil when absent/invalid.
Context-window overrides from config.json (model => positive integer).
Effective model when config.json is present; application and env precedence still applies.
Models list from config.json only, or nil when absent/invalid.
Resolved host-command boundary limits.
Load and resolve config.json.
Merge config defaults into Provider opts without clobbering explicit values.
UTC timestamp written by the last explicit model-catalog refresh, if present.
Resolved permission default (:auto, :ask, or :read_only).
Resolved reasoning effort, or nil to omit and let the model default.
Resolve one immutable model/backend snapshot from exactly one source-document read.
Resolve only the explicit Responses backend descriptor from one request snapshot.
Resolved text verbosity, or nil to omit and let the model default.
Accepted reasoning effort ids.
Resolved hosted web search config, or nil when disabled/absent.
Types
Functions
@spec bash_timeout_max_ms(keyword()) :: pos_integer()
@spec bash_timeout_ms(keyword()) :: pos_integer()
Whether model-assisted compaction is enabled (default false).
@spec compaction_tail_events(keyword()) :: pos_integer()
Anthropic models list from config.json only, or nil when absent/invalid.
@spec file_context_windows(keyword()) :: %{required(String.t()) => pos_integer()}
Context-window overrides from config.json (model => positive integer).
Effective model when config.json is present; application and env precedence still applies.
Models list from config.json only, or nil when absent/invalid.
@spec host_commands(keyword()) :: {:ok, %{required(String.t()) => non_neg_integer() | pos_integer()}}
Resolved host-command boundary limits.
@spec load(keyword()) :: load_result()
Load and resolve config.json.
Returns a JSON-serializable map with "path", "present", "effective", and
"warnings". Missing files yield defaults and an empty warning list.
@spec max_retries(keyword()) :: non_neg_integer()
Merge config defaults into Provider opts without clobbering explicit values.
UTC timestamp written by the last explicit model-catalog refresh, if present.
@spec permission_default(keyword()) :: Permissions.mode()
Resolved permission default (:auto, :ask, or :read_only).
Resolved reasoning effort, or nil to omit and let the model default.
Resolve one immutable model/backend snapshot from exactly one source-document read.
@spec responses_backend(keyword()) :: {:ok, :absent | Pixir.Providers.ResponsesBackend.t()} | {:error, map()}
Resolve only the explicit Responses backend descriptor from one request snapshot.
@spec stream_idle_timeout_ms(keyword()) :: non_neg_integer()
Resolved text verbosity, or nil to omit and let the model default.
@spec valid_reasoning_efforts() :: [String.t()]
Accepted reasoning effort ids.
Resolved hosted web search config, or nil when disabled/absent.