configuration ​

kage reads its configuration from ~/.config/kage/config.toml. The file is optional; sane defaults work without it. kage init writes a starter one.

Keys are grouped into tables:

[provider]
# active default model, provider:model qualified.
default_model = "anthropic:claude-sonnet-4-6"

[ui]
# bundled theme name, or a user theme under ~/.config/kage/themes/<name>.toml.
theme = "default"
# capture terminal mouse events. Toggle at runtime with :mouse.
mouse = true
# input card sizing (content rows, before the 2-row border chrome).
# the card grows with what you type, from input_min_lines up to
# input_max_lines, then scrolls internally. raise the max for a
# bigger composing area. min floored at 1, max capped at 64.
input_min_lines = 1
input_max_lines = 8

[plugins]
# override the plugin directory (default ~/.config/kage/plugins/).
# dir = "/path/to/plugins"
# if non-empty, only these plugin file stems load.
enabled = []

[sandbox]
# "local" (default in 0.1), "bubblewrap", or "sandbox-exec".
backend = "local"
# silence the "running unsandboxed" startup warning.
suppress_warning = false

[keybindings]
# chord -> builtin command name.
# bindings = { "ctrl+r" = "cancel" }

[loop]
# compact older history once the prompt fills this fraction of the
# model context window (0.0-1.0). Applies on next launch; also
# editable in the :settings dialog.
compaction_threshold = 0.8

Every table and key is optional; omitted values fall back to the defaults shown above.

layering ​

Configuration is merged lowest-to-highest precedence:

1. built-in defaults
2. ~/.config/kage/config.toml (user)
3. <workdir>/.kage/config.toml (project-local; commit it to share team settings)
4. KAGE_* environment variables

Env vars use KAGE_ with __ for nesting, e.g. KAGE_UI__THEME=catppuccin-mocha overrides the [ui].theme key.

environment variables ​

API keys are read from environment variables:

If multiple keys are present, the model id you pass with -m or configure as model picks the provider.

directories ​

XDG_CONFIG_HOME / XDG_DATA_HOME override the ~/.config and ~/.local/share roots. Skills and templates are also discovered under the project-local <workdir>/.kage/skills/ and <workdir>/.kage/templates/, plus any directory a plugin contributes via the resources_discover event.

skills and templates ​

A skill is a directory with a SKILL.md (YAML frontmatter name, description, optional disable_model_invocation) whose body is injected into the system prompt so the agent always sees it.

A prompt template is a single .md file (frontmatter name, description, argument-hint) whose body becomes a user message with positional substitution: $1, $2, ... ; $@ / $ARGUMENTS for all args joined; ${@:N:L} for a bash-style slice. Drop files in the directories above; no Lua required.