tools-only Configuration Layer
Package: src/tunacode/configuration/
What
Everything that can be configured by the user or the project. This layer reads tunacode.json, resolves paths, loads the bundled model registry, and exposes typed accessors for limits, pricing, and feature flags.
Key Files
| File | Purpose |
|---|---|
defaults.py |
DEFAULT_USER_CONFIG dict -- the fallback for every setting. |
user_config.py |
load_config() reads tunacode.json from ~/.config/. load_config_with_defaults() deep-merges user overrides onto defaults. |
settings.py |
ApplicationSettings dataclass -- app name, version, paths, internal tool list. PathConfig resolves ~/.config/tunacode.json. |
models.py |
load_models_registry() parses models_registry.json (bundled). parse_model_string() splits "provider:model_id". Accessors: get_providers(), get_models_for_provider(), get_provider_env_var(), get_provider_base_url(), get_model_context_window(), validate_provider_api_key(). |
paths.py |
Session storage directory, project ID derivation, home-dir resolution. |
limits.py |
get_max_tokens() -- resolves the effective max output tokens from user config. |
pricing.py |
Per-model pricing tables used to compute CostBreakdown. |
feature_flags.py |
Boolean feature toggles (e.g., experimental features). |
ignore_patterns.py |
Default file patterns excluded from grep/glob (.git, node_modules, etc.). |
How
At startup, StateManager.__init__() calls load_config_with_defaults() to build the merged user config. This config dict is stored on SessionState.user_config and read by every other layer.
Model resolution flow:
parse_model_string("openrouter:openai/gpt-4.1")returns("openrouter", "openai/gpt-4.1").get_provider_env_var("openrouter")returns"OPENROUTER_API_KEY".get_provider_base_url("openrouter")returns the API endpoint from the bundled registry.get_model_context_window("openrouter:openai/gpt-4.1")returns the token limit.
Why
Centralizing configuration avoids scattered os.getenv() calls. The bundled models_registry.json means users never need to know provider URLs or env-var names -- just pick a provider and model from the registry.