# Configuration Layer

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

- Skill: `tools-only/configuration-layer` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/configuration-layer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/configuration-layer/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/configuration-layer

---


# 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:
1. `parse_model_string("openrouter:openai/gpt-4.1")` returns `("openrouter", "openai/gpt-4.1")`.
2. `get_provider_env_var("openrouter")` returns `"OPENROUTER_API_KEY"`.
3. `get_provider_base_url("openrouter")` returns the API endpoint from the bundled registry.
4. `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.