Configuration

KosmoKrator uses a layered configuration system that lets you set global defaults, override them per project, and fine-tune individual settings at runtime. This page covers every config file location, all settings categories, environment variable expansion, and full YAML examples.

Config File Locations

Configuration is loaded from up to three YAML sources, merged in order. Later sources override earlier ones on a per-key basis.

1. Bundled defaults — config/kosmokrator.yaml inside the application. Ships with sane defaults for every setting. You never need to edit this file; it exists as the baseline.
2. User global config — ~/.kosmokrator/config.yaml. Your personal overrides that apply to every project. This is the right place for API keys, preferred provider/model, theme choice, and permission mode.
3. Project-level config — discovered by walking up from the current working directory to the filesystem root. At each directory level, KosmoKrator checks for .kosmokrator/config.yaml (priority) and .kosmokrator.yaml. The first match found wins, giving you per-project overrides. Use this to set a different model for a specific repo, enable plan mode by default, or adjust subagent concurrency for large monorepos.

Environment Variable Expansion

Any value in your YAML files can reference environment variables using the ${VAR_NAME} syntax. This is especially useful for API keys and paths that differ between machines.

agent:
  default_provider: anthropic

# API key pulled from the shell environment
# (set in ~/.zshrc, ~/.bashrc, or your CI secrets)
anthropic:
  api_key: ${ANTHROPIC_API_KEY}

audio:
  soundfont: ${HOME}/.kosmokrator/soundfonts/FluidR3_GM.sf2

If a referenced variable is not set, it is replaced with an empty string. This means unset variables are silently removed rather than causing an error at load time.

Runtime Settings — The /settings Command

Beyond YAML files, KosmoKrator provides an interactive /settings command inside the REPL. It opens a TUI settings editor where you can browse categories, change values, and save immediately.

• Navigate categories with arrow keys or tab.
• Toggle, choose, or type new values inline.
• Changes are saved instantly to the same YAML priority chain (user global config or project-level config) via SettingsManager.
• Some settings take effect immediately (applies now), others on the next turn (next turn), and others require a new session (next session).

Settings Reference

Every configurable setting is listed below, grouped by category. The Effect column indicates when a change takes effect: applies now (mid-conversation), next turn (after your next message), or next session (requires restarting KosmoKrator).

General

Controls the overall look and feel of the terminal interface.

Models

Select the LLM provider and model used for the main agent. The available choices are populated dynamically from your configured providers.

Agent

Controls the core agent behavior: operating mode, sampling parameters, and retry policy.

Subagents

Subagents are child agent processes spawned to handle parallel subtasks. You can configure separate providers and models at each depth level, plus concurrency and reliability controls.

Permissions

The permission system controls which tool calls require explicit user approval.

Integrations

KosmoKrator discovers integration packages (e.g. Plausible, CoinGecko, Celestial) from your composer.lock. Each integration exposes Lua-callable API functions via app.integrations.{name}. Integration settings are managed at runtime through /settings under the Integrations category.

Codex

The Codex section configures the built-in OAuth server used for authenticating with cloud providers and services.

Context & Memory

Fine-tune how KosmoKrator manages the conversation context window, compaction, pruning, and the persistent memory system.

Audio

KosmoKrator can compose and play a short musical piece after each agent response, reflecting the nature of the work performed. This requires a SoundFont file for MIDI playback.

YAML Configuration Examples

Below are complete ~/.kosmokrator/config.yaml examples for common setups. Copy one as your starting point and adjust to taste.

Anthropic (Claude)

# ~/.kosmokrator/config.yaml — Anthropic Claude setup
agent:
  default_provider: anthropic
  default_model: claude-sonnet-4-20250514
  temperature: 0.0
  max_retries: 3
  reasoning_effort: medium
  mode: edit

  # Use a cheaper model for subagents
  subagent_provider: anthropic
  subagent_model: claude-haiku-4-20250414
  subagent_max_depth: 3
  subagent_concurrency: 8

ui:
  renderer: auto
  intro_animated: true
  show_reasoning: false

tools:
  default_permission_mode: guardian

context:
  auto_compact: true
  memories: true

OpenAI

# ~/.kosmokrator/config.yaml — OpenAI setup
agent:
  default_provider: openai
  default_model: gpt-4.1
  temperature: 0.0
  max_retries: 3
  reasoning_effort: off

  subagent_provider: openai
  subagent_model: gpt-4.1-mini

ui:
  renderer: auto
  intro_animated: true

tools:
  default_permission_mode: guardian

Local Ollama

# ~/.kosmokrator/config.yaml — Local Ollama setup
agent:
  default_provider: ollama
  default_model: qwen3:32b
  temperature: 0.0
  max_retries: 0          # unlimited retries (local server may restart)

  # Smaller model for subagents to stay within local resources
  subagent_provider: ollama
  subagent_model: qwen3:8b
  subagent_max_depth: 2
  subagent_concurrency: 3

ui:
  renderer: auto
  intro_animated: false    # skip animation for quick iteration

tools:
  default_permission_mode: prometheus   # auto-approve for local-only use

Custom / OpenAI-Compatible Provider

# ~/.kosmokrator/config.yaml — Custom endpoint
agent:
  default_provider: custom
  default_model: my-fine-tuned-model
  temperature: 0.2
  max_retries: 5

  # Main agent uses the custom provider, subagents use OpenAI
  subagent_provider: openai
  subagent_model: gpt-4.1-mini

ui:
  renderer: ansi    # force ANSI for SSH sessions

tools:
  default_permission_mode: guardian

Custom providers that expose an OpenAI-compatible API can be configured by registering them in the provider setup. Use /settings under the Provider Setup category to add the base URL and API key.

Multi-Provider Mix

# ~/.kosmokrator/config.yaml — Use different providers at each depth
agent:
  default_provider: anthropic
  default_model: claude-sonnet-4-20250514
  temperature: 0.0
  reasoning_effort: high

  # Depth-1 subagents: fast Anthropic model
  subagent_provider: anthropic
  subagent_model: claude-haiku-4-20250414

  # Depth-2+ subagents: cheap OpenAI for bulk exploration
  subagent_depth2_provider: openai
  subagent_depth2_model: gpt-4.1-mini

  subagent_max_depth: 3
  subagent_concurrency: 12

  # Audio composition uses a small model to save cost
  audio_provider: openai
  audio_model: gpt-4.1-nano

audio:
  completion_sound: true
  soundfont: ${HOME}/.kosmokrator/soundfonts/FluidR3_GM.sf2
  max_duration: 6

tools:
  default_permission_mode: guardian

Environment Variables

KosmoKrator reads API keys and other secrets from environment variables. Set these in your shell profile (~/.zshrc, ~/.bashrc, etc.) or in your CI/CD environment.

Using Variables in YAML

Reference any environment variable in your YAML config with the ${VAR_NAME} syntax. This works for any value, not just API keys:

# Paths and keys from environment
audio:
  soundfont: ${HOME}/.kosmokrator/soundfonts/FluidR3_GM.sf2

session:
  history_dir: ${KOSMOKRATOR_DATA_DIR}/sessions

Full YAML Structure Reference

For reference, here is the complete top-level structure of kosmokrator.yaml with all sections:

agent:
  default_provider: ...       # LLM provider name
  default_model: ...          # Model identifier
  temperature: 0.0            # Sampling temperature
  max_retries: 0              # 0 = unlimited
  mode: edit                  # edit | plan | ask
  reasoning_effort: high      # off | low | medium | high
  subagent_provider: ...      # Depth-1 subagent provider
  subagent_model: ...         # Depth-1 subagent model
  subagent_depth2_provider: ... # Depth-2+ provider
  subagent_depth2_model: ...  # Depth-2+ model
  subagent_max_depth: 3
  subagent_concurrency: 10
  subagent_max_retries: 2
  subagent_idle_watchdog_seconds: 900
  audio_provider: ...         # Audio composition provider
  audio_model: ...            # Audio composition model
  system_prompt: |
    ...                       # Custom system prompt (advanced)

ui:
  renderer: auto              # auto | tui | ansi
  intro_animated: true
  theme: default
  show_reasoning: false       # Show model thinking before responses

codex:
  oauth_port: 9876            # OAuth callback server port

integrations:
  permissions_default: ask    # allow | ask | deny (default for integration ops)

tools:
  approval_required:          # Tools requiring explicit approval
    - file_write
    - file_edit
    - apply_patch
    - bash
    - shell_start
    - shell_write
    - execute_lua
  denied_tools: []            # Tools always blocked (overrides all modes)
  safe_tools:                 # Tools auto-approved in Guardian mode
    - file_read
    - glob
    - grep
    - task_create
    - task_update
    - task_list
    - task_get
    - shell_read
    - shell_kill
    - memory_save
    - memory_search
    - ask_user
    - ask_choice
    - subagent
    - lua_list_docs
    - lua_search_docs
    - lua_read_doc
  default_permission_mode: guardian
  bash:
    timeout: 120              # Bash command timeout (seconds)
    blocked_commands:
      - "rm -rf /"
  shell:
    wait_ms: 100              # Shell session poll interval
    idle_ttl: 300             # Shell session idle timeout
  blocked_paths:              # Glob patterns for blocked file paths
    - "*.env"
    - ".git/*"
    - "*.pem"
    - "*id_rsa*"
    - "*id_ed25519*"
    - "*.key"
  allowed_paths:              # Paths exempt from blocked_paths
    - "~/.kosmokrator"
    - "/tmp"
  guardian_safe_commands:      # Commands auto-approved in Guardian mode
    - "git *"
    - "ls *"
    - "pwd"
    - "cat *"
    - "head *"
    - "tail *"
    - "wc *"
    - "find *"
    - "which *"
    - "echo *"
    - "diff *"
    - "php vendor/bin/phpunit*"
    - "php vendor/bin/pint*"
    - "composer *"
    - "npm *"
    - "npx *"
    - "node *"
    - "python *"
    - "cargo *"
    - "go *"
    - "make *"

context:
  max_output_lines: 2000
  max_output_bytes: 50000
  reserve_output_tokens: 16000
  warning_buffer_tokens: 24000
  auto_compact_buffer_tokens: 12000
  blocking_buffer_tokens: 3000
  prune_protect: 40000
  prune_min_savings: 20000
  compact_threshold: 60
  memory_warning_mb: 50

session:
  auto_save: true
  history_dir: ~/.kosmokrator/sessions

audio:
  completion_sound: false
  soundfont: "~/.kosmokrator/soundfonts/FluidR3_GM.sf2"
  llm_timeout: 60
  max_duration: 8
  max_retries: 1