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 explains the model, workflows, and YAML examples. For the exhaustive schema table, use Settings Reference.

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.

Bundled defaults — config/kosmo.yaml inside the application. Ships with sane defaults for every setting. You never need to edit this file; it exists as the baseline.
User global config — ~/.kosmo/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.
Project-level config — discovered by walking up from the current working directory to the filesystem root. At each directory level, KosmoKrator checks for .kosmo/config.yaml (priority) and .kosmo.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.

Tip: The priority chain is project > global > bundled. A setting in a project-level config always wins over the same key in ~/.kosmo/config.yaml, which in turn overrides the bundled default.

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.

kosmo:
  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}/.kosmo/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).

Tip: Settings saved via /settings are written to your YAML config files, using the same priority chain as manual edits. To revert a runtime setting, clear it in /settings and the bundled defaults take over again.

Headless Settings CLI

Every setting exposed in /settings is also available from a non-interactive shell API. This is the preferred surface for CI images, bootstrap scripts, remote servers, and other coding agents that need to configure KosmoKrator without a TUI.

# Discover categories, keys, current values, sources, effects, and YAML paths
kosmo settings:list --json
kosmo settings:list --category permissions --json

# Inspect one setting and enumerate valid options
kosmo settings:get agent.default_provider --json
kosmo settings:options agent.default_provider --json
kosmo settings:options agent.default_model --provider openai --json

# Write one value to global or project config
kosmo settings:set agent.mode plan --global --json
kosmo settings:set tools.denied_tools "bash,file_write" --project --json
kosmo settings:set agent.default_model gpt-5.4-mini --provider openai --global --json

# Apply multiple settings atomically from JSON
jq -n '{
  scope: "global",
  settings: {
    "agent.default_provider": "openai",
    "agent.default_model": "gpt-5.4-mini",
    "tools.default_permission_mode": "guardian"
  }
}' | kosmo settings:apply --stdin-json --json

# Remove an override so lower-priority config/defaults take over
kosmo settings:unset agent.mode --project --json

# Diagnose whether headless runs are ready
kosmo settings:doctor --json
kosmo settings:examples --json

Write responses include both the value written to the requested scope and the effective value after the normal project/global/default priority chain is applied. This matters when, for example, a global write is masked by a project override.

Values are parsed by setting type: toggles accept on/off, true/false, or 1/0; list settings accept comma, newline, or JSON-array input; JSON/YAML settings are parsed structurally instead of by string splitting. Machine-readable commands return the resolved value, display value, source (default, global, or project), effect timing, and valid options.

Secrets: API keys and tokens are not written through settings:set. Use providers:configure, secrets:set, or the gateway-specific configure command so secret values stay in the managed secret store and are only reported as masked status.

Settings Reference

The most important settings are 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). The complete reference is in Settings Reference.

General

Controls the overall look and feel of the terminal interface.

Setting	Type	Default	Description	Effect
`ui.renderer`	choice: `auto`, `tui`, `ansi`	`auto`	Preferred renderer. `auto` selects the interactive TUI when the terminal supports it and falls back to pure ANSI otherwise. Force one or the other with `tui` or `ansi`.	next session
`ui.theme`	choice	`default`	Terminal color theme preset. Additional themes may be added in future releases.	next session
`ui.intro_animated`	toggle	`on`	Play the cosmic startup animation before opening the REPL. Disable with `off` or the `--no-animation` CLI flag for instant startup.	next session
`ui.show_reasoning`	toggle	`off`	Display model reasoning/thinking content before each response. When on, the agent’s chain-of-thought output is shown inline before the final answer.	applies now

Models

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

Setting	Type	Default	Description	Effect
`agent.default_provider`	dynamic choice	(first configured provider)	The LLM provider used when a new session starts. Providers are registered in the provider configuration (Anthropic, OpenAI, Ollama, OpenRouter, and dozens more).	next session
`agent.default_model`	dynamic choice	(provider default)	The model to use with the selected provider. The list of available models depends on the chosen provider.	next session

Tip: You can switch providers and models mid-session with /models without restarting. The command shows recent and likely choices first; full inventory remains in /settings.

Agent

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

Setting	Type	Default	Description	Effect
`agent.mode`	choice: `edit`, `plan`, `ask`	`edit`	Starting mode for interactive sessions. edit grants full read-write tool access. plan allows reading and planning but no file modifications. ask is a pure chat mode with no tool use.	applies now
`agent.temperature`	number (0–2)	`0.0`	Sampling temperature for the LLM. Lower values produce more deterministic output; higher values increase creativity and variation.	applies now
`agent.max_tokens`	number	(model default)	Override the maximum number of output tokens per LLM response. Leave unset to use the model’s built-in limit.	applies now
`agent.max_retries`	number	`0`	Retry limit for transient provider failures (HTTP 429, 500, 503, network timeouts). Set `0` for unlimited retries with exponential backoff.	applies now
`agent.reasoning_effort`	choice: `off`, `low`, `medium`, `high`	`high`	Controls extended thinking / chain-of-thought reasoning for models that support it (e.g., Claude with extended thinking, OpenAI o-series). `off` disables reasoning parameters entirely.	applies now

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.

Setting	Type	Default	Description	Effect
`agent.subagent_provider`	dynamic choice	(inherits main provider)	Provider for depth-1 subagents. Leave empty to use the main agent’s provider.	next session
`agent.subagent_model`	dynamic choice	(inherits main model)	Model for depth-1 subagents. Leave empty to use the main agent’s model.	next session
`agent.subagent_depth2_provider`	dynamic choice	(inherits subagent provider)	Provider for depth-2 and deeper subagents. Falls back to the subagent provider, then the main agent provider.	next session
`agent.subagent_depth2_model`	dynamic choice	(inherits subagent model)	Model for depth-2 and deeper subagents. Falls back to the subagent model, then the main agent model.	next session
`agent.subagent_max_depth`	number	`3`	Maximum nesting depth for spawned agent trees. A value of 3 means the main agent (depth 0) can spawn subagents (depth 1), which can spawn sub-subagents (depth 2), which can spawn depth-3 agents.	next session
`agent.subagent_concurrency`	number	`10`	Maximum number of subagents running concurrently across all depths. Set `0` for unlimited.	next session
`agent.subagent_max_retries`	number	`2`	How many times a failed subagent is retried before reporting the failure to the parent. Set `0` for no retries.	next session
`agent.subagent_idle_watchdog_seconds`	number	`900`	Cancel a subagent if it stops making progress updates for this many seconds. Set `0` to disable the watchdog.	next session

Tip: A common pattern is to use a powerful model (e.g., Claude Opus) for the main agent, a fast model (e.g., Claude Sonnet) for depth-1 subagents, and an even cheaper model (e.g., Claude Haiku) for depth-2+. This optimizes cost while keeping the coordinator sharp.

Permissions

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

Setting	Type	Default	Description	Effect
`tools.default_permission_mode`	choice: `guardian`, `argus`, `prometheus`	`guardian`	Default permission policy for tool calls.

Guardian — asks approval for all write operations and untrusted commands. Safe read commands (git, ls, cat, etc.) are auto-approved.
Argus — asks approval for every tool call, including reads. Maximum oversight.
Prometheus — auto-approves everything. Full autonomy, no prompts. Use with caution.

Integrations

KosmoKrator discovers installed OpenCompany integration packages from your composer.lock. Current packages may use either the newer opencompanyapp/integration-* prefix or the legacy opencompanyapp/ai-tool-* prefix. Each integration exposes Lua-callable API functions via app.integrations.{name} and headless shell commands via kosmo integrations:*. Integration settings are managed at runtime through /settings under the Integrations category. See Integrations CLI for the full headless command and Lua reference.

Setting	Type	Default	Description	Effect
`integrations.permissions_default`	choice: `allow`, `ask`, `deny`	`ask`	Default permission policy for integration API operations not explicitly configured.

allow — auto-approve the operation.
ask — prompt the user before executing.
deny — block the operation outright.

| applies now |

MCP

MCP server definitions intentionally live in JSON so projects can share config with other coding agents. KosmoKrator reads global ~/.kosmo/mcp.json, project .vscode/mcp.json, project .cursor/mcp.json, and project .mcp.json. The portable shape is a top-level mcpServers object; VS Code/Cursor compatibility files may use top-level servers.

{
  "mcpServers": {
    "github": {
      "command": "github-mcp-server",
      "args": [],
      "env": {
        "GITHUB_TOKEN": "${KOSMO_SECRET:mcp.github.env.GITHUB_TOKEN}"
      }
    }
  }
}

Kosmo-only policy stays in YAML config because trust and permissions should not be committed into a shared portable MCP file unless the project intentionally owns that policy.

Setting	Type	Default	Description	Effect
`kosmo.mcp.permissions_default`	choice: `allow`, `ask`, `deny`	`ask`	Default read/write policy for MCP tool operations not explicitly configured.	applies now
`kosmo.mcp.servers.SERVER.permissions.read`	choice: `allow`, `ask`, `deny`	inherits default	Read policy for one MCP server. Also applies to resources and prompts.	applies now
`kosmo.mcp.servers.SERVER.permissions.write`	choice: `allow`, `ask`, `deny`	inherits default	Write policy for one MCP server. Tools without MCP `readOnlyHint` are treated as write.	applies now
`kosmo.mcp.trust.SERVER.fingerprint`	string	unset	Fingerprint written by `mcp:trust` after reviewing a project MCP command.	applies now

kosmo:
  mcp:
    permissions_default: ask
    servers:
      github:
        permissions:
          read: allow
          write: ask

Configure headlessly with mcp:add, mcp:trust, mcp:secret:set, and settings:set. See MCP for the full command reference.

Web

Optional external web providers are configured under web.*. They are not default-on: native web_fetch remains the normal fetch path, while web_search, web_fetch_external, web_extract, and web_crawl require explicit provider enablement.

Setting	Type	Default	Description	Effect
`web.search.enabled`	toggle	`off`	Enable the optional `web_search` tool.	next session
`web.search.provider`	choice	unset	Default search provider: Tavily, Firecrawl, Exa, Brave, Parallel, Jina, SearXNG, Perplexity, OpenAI native, or Anthropic native.	next session
`web.fetch.provider`	choice	`native`	Default fetch provider. Keep `native` for built-in web fetch; select an external provider for `web_fetch_external`.	next session
`web.fetch.allow_external`	toggle	`off`	Allow external extract/fetch tools. These tools still require approval by default.	next session
`web.crawl.enabled`	toggle	`off`	Enable `web_crawl`.	next session
`web.crawl.provider`	choice	unset	Default crawl provider, currently Tavily or Firecrawl.	next session
`web.providers.PROVIDER.enabled`	toggle	`off`	Enable one provider. API keys can come from managed settings, provider-specific env vars, or provider config.	next session
`web.providers.searxng.base_url`	string	unset	Base URL for a trusted SearXNG instance.	next session
`web.native.mode`	choice: `cached`, `live`	`cached`	Provider-native search hint for OpenAI and Anthropic adapters.	next session

# Enable Tavily search globally without putting a key in YAML
kosmokrator web:configure tavily --api-key-env=TAVILY_API_KEY \
  --enable --search --global --json

# Enable Firecrawl extract/fetch for one project
kosmokrator web:configure firecrawl --api-key-env=FIRECRAWL_API_KEY \
  --enable --fetch --project --json

# Diagnose the effective web setup
kosmokrator web:doctor --json

Gateway

The Gateway category controls external chat surfaces. Today the shipped gateway is Telegram, started with kosmo gateway:telegram. Gateway state lives partly in normal config and partly in the local secret store, so you usually manage it through /settings rather than by editing YAML directly.

Setting	Type	Default	Description	Effect
`gateway.telegram.enabled`	toggle	`off`	Enable or disable the Telegram gateway runtime.	next session
`gateway.telegram.session_mode`	choice: `chat`, `chat_user`, `thread`, `thread_user`	`thread`	Controls how Telegram chats map to Kosmo sessions.

chat — one session per chat
chat_user — one session per chat/user pair
thread — one session per Telegram thread/topic
thread_user — one session per thread/user pair

Telegram token: The bot token is managed through /settings → Gateway and stored outside normal YAML by default. You can also provide it via KOSMO_TELEGRAM_BOT_TOKEN.

Codex

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

Setting	Type	Default	Description	Effect
`codex.oauth_port`	number	`9876`	The local port used by the OAuth callback server when authenticating with external providers. Change this if the default port conflicts with another service.	next session

Context & Memory

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

Setting	Type	Default	Description	Effect
`context.memories`	toggle	`on`	Enable the persistent memory system. When on, the agent can recall facts from previous sessions and save new memories for future use.	next turn
`context.auto_compact`	toggle	`on`	Automatically compact the conversation context before it hits the model’s token limit. When the remaining input budget drops below the auto-compact buffer, the agent summarizes older messages to free space.	next turn
`context.compact_threshold`	number	`60`	Legacy threshold percentage for the compaction fallback mechanism. Lower values trigger compaction sooner.	next turn
`context.reserve_output_tokens`	number	`16000`	Headroom reserved for the assistant’s response. This is subtracted from the model’s context window to determine how many tokens are available for input (system prompt + conversation history).	next turn
`context.warning_buffer_tokens`	number	`24000`	When the remaining input budget drops below this threshold, KosmoKrator displays context pressure warnings in the status bar.	next turn
`context.auto_compact_buffer_tokens`	number	`12000`	When the remaining input budget drops below this threshold, auto-compaction triggers (if enabled).	next turn
`context.blocking_buffer_tokens`	number	`3000`	Hard-stop buffer to prevent overrunning the model’s context window. If remaining budget hits this, the agent force-compacts before the next LLM call.	next turn
`context.prune_protect`	number	`40000`	Number of recent tool-result tokens protected from micro-pruning. Ensures the agent retains full detail for the most recent tool outputs.	next turn
`context.prune_min_savings`	number	`20000`	Minimum token savings required for a prune pass to be accepted. Prevents thrashing from tiny, repeated prune operations.	next turn
`context.max_output_lines`	number	`2000`	Maximum lines retained from tool output before truncation.	next turn
`context.max_output_bytes`	number	`50000`	Maximum bytes retained from tool output before truncation.	next turn

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.

Setting	Type	Default	Description	Effect
`audio.completion_sound`	toggle	`off`	Compose and play a short musical piece after each agent response. The composition reflects the nature of the completed work.	applies now
`audio.soundfont`	text (file path)	`~/.kosmo/soundfonts/FluidR3_GM.sf2`	Path to a SoundFont (.sf2) file for MIDI playback. FluidR3 GM is recommended for a good general-purpose sound set.	applies now
`audio.llm_timeout`	number (seconds)	`60`	Maximum seconds to wait for the AI to compose a musical piece before falling back to a built-in omen sound.	applies now
`audio.max_duration`	number (seconds)	`8`	Maximum length of the composed musical piece in seconds.	applies now
`audio.max_retries`	number	`1`	Number of times to retry if the LLM fails to generate a valid music composition script.	applies now
`agent.audio_provider`	dynamic choice	(inherits main provider)	Provider for the audio composition LLM call. Leave empty to use the main agent’s provider.	next session
`agent.audio_model`	dynamic choice	(inherits main model)	Model for the audio composition LLM call. Leave empty to use the main agent’s model. A cheap, fast model works well here.	next session

YAML Configuration Examples

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

Anthropic (Claude)

# ~/.kosmo/config.yaml — Anthropic Claude setup
kosmo:
  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

Tip: Set ANTHROPIC_API_KEY in your shell environment rather than putting it in the YAML file. KosmoKrator reads it automatically.

OpenAI

# ~/.kosmo/config.yaml — OpenAI setup
kosmo:
  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

# ~/.kosmo/config.yaml — Local Ollama setup
kosmo:
  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

Tip: With local models, keep subagent concurrency low to avoid saturating your GPU. A concurrency of 2–4 is typically the sweet spot for consumer hardware.

Custom / OpenAI-Compatible Provider

# ~/.kosmo/config.yaml — Custom endpoint
kosmo:
  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

# ~/.kosmo/config.yaml — Use different providers at each depth
kosmo:
  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}/.kosmo/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.

Variable	Description
`ANTHROPIC_API_KEY`	API key for Anthropic (Claude models)
`OPENAI_API_KEY`	API key for OpenAI (GPT models)
`GOOGLE_API_KEY`	API key for Google (Gemini models)
`MISTRAL_API_KEY`	API key for Mistral
`GROQ_API_KEY`	API key for Groq
`XAI_API_KEY`	API key for xAI (Grok models)
`DEEPSEEK_API_KEY`	API key for DeepSeek
`OPENROUTER_API_KEY`	API key for OpenRouter (multi-provider gateway)
`TOGETHER_API_KEY`	API key for Together AI
`FIREWORKS_API_KEY`	API key for Fireworks AI

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
kosmo:
  audio:
    soundfont: ${HOME}/.kosmo/soundfonts/FluidR3_GM.sf2

  session:
    history_dir: ${KOSMO_DATA_DIR}/sessions

Full YAML Structure Reference

For reference, here is the complete structure for user and project config files. The bundled config/kosmo.yaml stores the same settings as defaults, while ~/.kosmo/config.yaml and .kosmo/config.yaml should place KosmoKrator runtime settings under the canonical kosmo: root.

kosmo:
  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)

  mcp:
    permissions_default: ask    # allow | ask | deny (default for MCP ops)
    servers:
      github:
        permissions:
          read: allow
          write: ask

  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
      - "~/.kosmo"
      - "/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: ~/.kosmo/sessions

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

Tip: You only need to include the keys you want to override. KosmoKrator merges your partial config on top of the bundled defaults, so a three-line config file is perfectly valid.