configuration
kage reads its configuration from ~/.config/kage/config.toml. The file is optional, and sane defaults work without it. kage init writes a starter one. A config that does not load stops kage with the error instead of running on defaults, and kage doctor names the file to fix.
The TUI also runs ~/.config/kage/init.lua after this file, so anything set there wins. The [ui], [loop] and [agents] keys that are options and the [keybindings] table feed the same settings init.lua sets. See lua config.
Keys are grouped into tables:
[provider]
# model used when -m/--model is absent. it beats the last-used model
# but only while its provider has credentials. otherwise kage uses the
# last model you ran, then the first provider with credentials.
default_model = "anthropic/claude-sonnet-4-6"
[ui]
# bundled theme name, or a user theme under ~/.config/kage/themes/<name>.toml.
theme = "default"
# the themes "default" picks on a dark and on a light terminal background.
# theme_dark = "kage-shadow"
# theme_light = "kage-dawn"
# capture terminal mouse events. Toggle at runtime with /mouse.
mouse = true
# prompt editing style: "modeless" or "vim".
editor = "modeless"
# input box sizing (content rows, not counting its two rules).
# the box 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
# default thinking level for new sessions: off, minimal, low,
# medium, high, xhigh, max, or ultra. left unset, kage uses high, or the nearest
# level the model accepts, and shows it as "high (auto)". alt+t
# still cycles it per session.
# thinking_level = "medium"
# what prints to the terminal after you quit the TUI: "full" (the
# whole conversation as plain text), "last" (from your last prompt
# on) or "none". the session file path follows when one was recorded.
transcript_on_exit = "full"
[plugins]
# override the plugin directory (default ~/.config/kage/plugins/).
# `~` expands to home, and relative paths resolve against ~/.config/kage.
# dir = "/path/to/plugins"
# plugins that do not load, by file stem or package directory. a
# project config can add to this list but never shorten it.
# (`enabled`, an allowlist, still works but is deprecated.)
disabled = []
# the plugin registry `kage plugin` installs from (default: kura).
# read from this file only; a project config cannot set it.
# registry = "https://kura.kage.qaidvoid.dev/"
[shell]
# Program the shell tool runs commands with: `bash` (the default on
# Linux and macOS), `pwsh` (the default on Windows), `fish`, `zsh`, or
# an absolute path. The tool description and the prompt's environment
# block name it, so the model writes commands in that shell's syntax.
# User `!` commands run with the same program. Known Windows shells
# (powershell, pwsh, cmd) get their own command flag; every other
# program is driven with `-c`.
# program = "fish"
# Glob patterns of environment variables to hide from shell commands
# (case-sensitive, matched against the whole name, so "*_TOKEN" covers
# GITHUB_TOKEN). Empty leaves the environment untouched.
# scrub_env = ["*_TOKEN", "*_SECRET", "*_KEY", "*_PASSWORD"]
scrub_env = []
[tools.rename]
# advertise a tool under another name: the model sees only the new
# name, while execution and permission rules keep working under the
# real one. keys are real tool names, values are advertised names.
# unknown tools are ignored, and plugin tools can rename themselves
# with `kage.rename_tool({ from = "shell", to = "run_command" })`.
# tool cards in the transcript, the ACP kind hints, and read-only
# grouping keep using the real name.
# shell = "run_command"
# web_fetch = "browse"
[tools.web_search]
# the engine `web_search` asks: "duckduckgo" (the default, no key),
# "searxng", a SearXNG instance at `url` that allows the json format,
# or "brave", the Brave Search API with the key in `api_key_env`
# (default BRAVE_API_KEY).
# engine = "searxng"
# url = "https://searx.example.org"
# engine = "brave"
# api_key_env = "BRAVE_API_KEY"
# every [tools.<name>] table also takes `enabled` and `description`,
# and the built-in tools take their limits. see "built-in tools" below.
# enabled = false
# count = 8 # results when the call sets no count
# max_count = 20 # the most a call may ask for
# timeout_ms = 20000
[tools.generate_image]
# the images endpoint the generate_image tool calls. Without one the
# tool is not offered. See "image generation" below.
# provider = "openai"
# model = "gpt-image-2"
[tools.edit_image]
# the images endpoint the edit_image tool calls. Without one the
# tool is not offered. See "image editing" below.
# provider = "openai"
# model = "gpt-image-2"
[tools.generate_speech]
# the speech endpoint the generate_speech tool calls. Without one the
# tool is not offered. See "speech" below.
# base_url = "https://speech.example.com/v1"
# model = "speech-small"
# voice = "alloy"
[tools.generate_music]
# the music endpoint the generate_music tool calls. Without one the
# tool is not offered. See "music" below.
# base_url = "https://music.example.com/v1"
# model = "music"
[keybindings]
# the key <leader> expands to in bindings: one key, default a backslash.
# leader = "<C-x>"
# ms a key that starts a longer mapping waits for more keys.
timeoutlen = 1000
# key -> command line, or `action:<Name>` for a built-in action
# (see the keybindings guide). Every binding maps in mode g.
# bindings = { "f6" = "theme set kage-dawn", "<leader>s" = "settings" }
[loop]
# compact older history once the prompt fills this fraction of the
# model context window (0.0 to 1.0). Compaction also fires early when
# the remaining room can no longer hold a full reply. Applies to the
# next session, and the /settings dialog edits it too.
compaction_threshold = 0.8
# how many times a turn that failed transiently (a dropped or stalled
# stream, a 5xx, rate limiting) is re-issued before the error surfaces
# (0 to 10). 0 turns auto-retry off. Applies to the next session.
max_provider_retries = 4
[agents]
# how deep agents may nest (0 to 3). 0 removes the agent tool, and 1
# lets only the main session start agents.
max_depth = 1
# how many agents run at once (1 to 16). further agents wait their turn.
max_running = 4
# most items one swarm call may run, one child agent per item (2 to
# 128). a call listing more fails.
swarm_max_items = 32
# milliseconds one swarm child may run, from its run start (1000 to
# 86400000). on deadline the child is cancelled.
swarm_timeout_ms = 7200000
# model agents run when neither the agent call nor the agent's
# definition names one, as provider/model. "inherit" uses the parent's.
model = "inherit"
# thinking level agents run with when neither the call nor the
# definition names one: inherit, off, minimal, low, medium, high, xhigh,
# max or ultra.
thinking = "inherit"
# turns with tool calls one agent run may take (0 to 10000, 0 for no
# limit). the agent gets one warning turn to reply first.
max_turns = 0
# seconds one agent run may take (0 to 86400, 0 for no limit).
timeout = 0
# tokens all agents of a session may use between two of your prompts
# (0 to 1000000000, 0 for no limit).
budget = 0
[permissions]
# tool permission rules. built-in tools are allowed unless configured
# and MCP tools ask. see the permissions guide for the full reference.
# confine_paths = false
# [permissions.tools.shell]
# default = "ask"
# allow = ["git *"]
# deny = ["rm -rf *"]
# [permissions.mcp]
# github = "allow" # action for every tool of one MCP server
[mcp]
# let MCP servers ask your default model for completions. default false.
allow_sampling = false
# one table per server. see the mcp guide for the full reference.
# [mcp.servers.linear]
# url = "https://mcp.linear.app/mcp"
# optional OAuth settings for a server that needs a login:
# [mcp.servers.linear.oauth]
# client_id = "kage-4f2c" # pre-registered client, skips registration
# scope = "read write" # overrides the scope the server advertisesEvery table and key is optional. Omitted values fall back to the defaults shown above. The two swarm keys under [agents] tune the swarm command: swarm_max_items caps how many items one call may run, and swarm_timeout_ms caps one child's runtime in milliseconds.
When kage writes this file itself (saving /settings, or answering "always allow" to a permission prompt), it changes only the keys involved. Your comments, key order and every other line stay as you wrote them. See permissions for the rules reference, agents for the [agents] limits, and mcp for MCP servers and OAuth logins.
built-in tools
Every tool the model can call is configured under [tools.<name>], keyed by its real name (never a [tools.rename] target). Two keys work for any tool, built-in, plugin or MCP:
enabled = falseremoves the tool. The model never sees it, and a call to it fails as an unknown tool. Sub-agents, plan mode andkage mcp servelose it too.description = "..."replaces the description the model reads. Use it to steer a model ("preferrg"), or to shorten a description for a small context window.
A project's [tools] table applies only once you trust the project (see project config and trust).
[tools.web_search]
enabled = false # an MCP server does search instead
[tools.web_fetch]
enabled = false
[tools.shell]
description = "Run one shell command. Prefer `rg` over `grep`."
timeout_ms = 300000 # default timeout when the call sets none
[tools.ask_user_question]
enabled = false # never stop to ask; decide and carry on
[tools.github__delete_repository]
enabled = false # MCP tools are `<server>__<tool>`The built-in tools also take their limits. The tool's description and input schema state the value in effect, so the model sees your limit, not the default. [tools.web_search] max_count above 20 is honoured for DuckDuckGo and SearXNG, but Brave's API documents count as max 20, so a Brave search is clamped to 20 whatever the config says.
| Table | Key | Default | What it bounds |
|---|---|---|---|
[tools.read] | max_bytes | 2000000 | bytes one read returns before it is cut |
[tools.edit] | max_bytes | 2000000 | largest file the tool will edit |
[tools.grep] | max_matches | 1000 | matches when the call sets no max_matches |
max_line_chars | 300 | characters kept of one matching line | |
[tools.find] | max_entries | 5000 | paths listed before the output is cut |
[tools.ls] | max_entries | 5000 | entries listed before the output is cut |
[tools.shell] | timeout_ms | 120000 | timeout when the call sets no timeout_ms |
max_output_bytes | 100000 | bytes kept of each of stdout and stderr | |
[tools.web_fetch] | max_bytes | 2000000 | body bytes when the call sets no max_bytes |
max_bytes_limit | 5000000 | the most a call may ask for | |
timeout_ms | 30000 | whole-request timeout | |
max_redirects | 5 | redirects followed | |
[tools.web_search] | count | 8 | results when the call sets no count |
max_count | 20 | the most results a call may ask for | |
timeout_ms | 20000 | whole-request timeout |
The shell program and the environment scrub stay in [shell]. Every value in a typed table can also come from the environment, such as KAGE_TOOLS__SHELL__TIMEOUT_MS=300000 or KAGE_TOOLS__WEB_FETCH__ENABLED=false.
An MCP tool's <server>__<tool> table is the exception: it is TOML only. The environment provider splits variable names on __, so KAGE_TOOLS__GITHUB__DELETE_REPOSITORY__ENABLED=false would arrive as tools.github.delete_repository.enabled, a table no tool reads. kage refuses to start on it rather than leaving the tool enabled, so write the table in the config file.
A [tools.<name>] table takes enabled and description and nothing else. Any other key is refused, so a disable meant for safety cannot quietly do nothing because it was spelled [tools.web-search] or [tools.Shell]: a name that matches no tool is reported as a warning once the registry is built.
kage refuses to start on a value no tool could use: an empty description, a zero limit, a max_bytes above max_bytes_limit, a max_bytes above 1 GiB, or a count above max_count. Disabling exit_plan leaves plan mode with no way out but /plan, and disabling todo_list, agent or swarm takes those features away from the model, so do that on purpose. kage mcp serve --tools refuses a tool you disabled, under its real name or a [tools.rename] one.
To change what a tool does rather than what it is told, a plugin can replace it with kage.override_tool (see the plugin API).
layering
Configuration is merged lowest-to-highest precedence:
- built-in defaults
~/.config/kage/config.toml(user)<workdir>/.kage/config.toml(project-local, commit it to share team settings)KAGE_*environment variables
Env vars use KAGE_ with __ for nesting, e.g. KAGE_UI__THEME=kage-shadow overrides the [ui].theme key.
In the TUI, init.lua runs after all of these. An option it sets, such as kage.opt.theme, wins over every layer above.
project config and trust
A cloned repository should not gain power just because you opened it, so a project's .kage/config.toml passes only the keys that are safe on their own while the project is untrusted:
[ui],[keybindings],[loop]and[agents]in fullprovider.default_modelplugins.disabled, which a project can add to but never shorten
Every other project key waits for trust. That includes [mcp] (servers, their oauth tables and allow_sampling), [permissions] (including [permissions.mcp]), all of [shell] (both program and scrub_env), [tools] (enabled, description, limits, rename and [tools.web_search]), plugins.capabilities, plugins.dir, plugins.enabled, any key kage does not know, the agent definitions in .kage/agents/ (see agents) and the skills in .kage/skills/. All of them share one trust decision.
The [providers] table, [acp.agents], [host] (see shared host), [models], plugins.registry and the media tables [tools.generate_image], [tools.edit_image], [tools.generate_speech] and [tools.generate_music] are never read from a project, trusted or not.
When the TUI starts in a project that sets any of these, it lists what the project asks for (server commands and URLs with every other server field such as env, sampling, capability grants, permission rules, tool settings, shell settings, project agents) and asks Trust this project? [y/N]. Answering yes records the trust. Any other answer starts kage with those tables and agents ignored.
A trusted project's [tools.<name>] enabled = true turns on a tool your own config disables, so a tool can stay off everywhere but in one project.
Print mode, kage rpc and kage mcp serve cannot ask. They print one warning on stderr and ignore the tables and agents. Run kage trust in the project directory to allow them, and kage trust --revoke to take the trust back. An editor driving kage rpc needs kage trust once per project.
Trust covers the values as they are when you approve them. Your answer is bound to a digest of the whole gated set, so a file edited between the prompt and your answer is refused rather than trusted unseen, even when the prompt lines alone cannot tell the difference. Editing a server command, a permission rule or a capability grant, or adding, removing or editing a project agent or skill file, makes kage ask again, and the prompt then also shows what changed since you approved it: old and new values for config keys, and a diff for changed agent and skill files. Reordering keys does not. The whole table is ignored while untrusted, even settings that only tighten your rules, such as a project that only adds deny patterns. kage doctor reports an untrusted project file and lists what changed.
Trusted projects are recorded in ~/.local/state/kage/trust.json, keyed by the project directory: the gated config values as JSON plus, for each project agent and skill file, a SHA-256 of its text. The approved texts are stored once under ~/.local/state/kage/trust/blobs/, one file per distinct content, shared by every project that approved the same file. Kage converts an older store to this shape the first time it reads it.
trusting directories
You can trust whole directories up front from your user config, so projects under them never prompt:
[trust]
paths = ["~/dev/personal", "~/work/kage"]
[trust.parts]
"~/work/client" = ["instructions", "skills"]A path in paths fully trusts every project under it: the gated tables, project agents, skills and AGENTS.md all load, and edits never ask again. Be careful what you list: a path trusts every repository you later clone under it, not just the projects there today.
A [trust.parts] entry trusts only the named parts under a directory. The parts are instructions (the project AGENTS.md), agents (the project agent files), skills (the project skills), and one per gated table: mcp, permissions, tools, shell and plugins. Every other part still prompts as usual, and an unknown part name is a config error. A directory covered by several entries gets the union of them all.
Config trust is standing trust. It never expires when the project's files change, and it is never written to trust.json. A stored kage trust record is read with the parts your entries cover removed, so covering another part later never makes kage ask again about the parts the record already approved. It is read from the user config only, so a project's own [trust] table never applies. Entries must name an absolute path, with ~ for the home directory: a relative entry is a config error, because it would resolve against the directory kage was started from. Matching expands ~ and compares path components, so ~/dev does not match ~/devil, and a listed path that does not exist matches nothing. A "/" key in [trust.parts] trusts those parts in every project, and paths = ["~"] trusts everything.
kage trust in a path-trusted project reports the entry that matched, and kage doctor lists the trusted parts.
image generation
The generate_image tool lets any model make an image from a prompt, through an endpoint that speaks the OpenAI Images API (POST {base_url}/images/generations). A model that draws on its own needs no tool (see providers); this is for the others. kage offers it only when [tools.generate_image] names an endpoint and a model:
# Reuse a provider kage already reaches, with its base URL, key and
# headers.
[tools.generate_image]
provider = "openai"
model = "gpt-image-2"Or name the endpoint itself. base_url wins when both are set.
[tools.generate_image]
base_url = "https://images.example.com/v1"
api_key_env = "IMAGES_API_KEY" # or a key saved for the tool, below
headers = { X-Team = "art" }
model = "image-small"
timeout_secs = 180 # the whole request, 1 to 3600To keep the key out of the environment, save it for the tool with kage auth login generate_image and leave out api_key_env. A variable named in api_key_env comes first when it is set, and the saved key fills in when it is not. With neither, no key is sent.
provider names openai, an OpenAI-compatible provider, or a [providers.custom.<id>] of kind openai. kage's anthropic and google providers speak other APIs and cannot be named; a server's OpenAI-compatible images endpoint can be given as base_url instead. When the table does not resolve (a key that is not set, a provider of another kind, no model), kage says why on stderr and starts without the tool. enabled = false keeps a configured table but leaves the tool out, and description replaces the one the model reads, as for every tool. The same holds for edit_image, generate_speech and generate_music below.
The image comes back with the call: the TUI, the desktop and editors show it, it stays in the session, and a model that reads images in tool results (Claude) sees it. /image save writes it into the project. A call may also name a path in the workspace to save it there at once; an existing file is never replaced, and a path outside the workspace is refused before the server is asked. A server that answers with a link instead of the image is followed only when the link is on the endpoint's own host: kage fetches it without the key and without following a redirect. A link to any other host is refused.
The tool counts as a write: plan mode and a read-only session refuse it, as they refuse write, and permission rules name it generate_image. Each call costs a generation, so to approve each one first:
[permissions.tools.generate_image]
default = "ask"image editing
The edit_image tool changes an image you already have from a prompt. It takes one PNG, JPEG or WebP image plus the prompt: a file from the workspace, or, when the call names none, the newest image in an earlier message, such as one generate_image made in a previous step or one you attached. It sends both to an OpenAI-compatible Images API (POST {base_url}/images/edits) as a multipart form. The edited image comes back with the call, exactly as a generated one does. kage offers it only when [tools.edit_image] names an endpoint and a model:
# Reuse a provider kage already reaches, with its base URL, key and
# headers.
[tools.edit_image]
provider = "openai"
model = "gpt-image-2"Or name the endpoint itself. base_url wins when both are set.
[tools.edit_image]
base_url = "https://images.example.com/v1"
api_key_env = "IMAGES_API_KEY" # or a key saved for the tool, below
model = "image-edit"The table takes the same keys as [tools.generate_image], and the rules for what provider may name are as for image generation. It is its own table because an edit server often serves another model name, and because it has its own permission rule. To keep the key out of the environment, save it for the tool with kage auth login edit_image and leave out api_key_env.
A source file is read only from inside the workspace, even with confine_paths = false, because the file is uploaded. Either source may be at most 16 MiB. One image goes in per call. There is no mask. A path saves the result and never replaces an existing file, the source included: the name gets -2, -3 and so on.
The tool counts as a write and uploads a file: plan mode and a read-only session refuse it, as they refuse write, and permission rules name it edit_image. Each call uploads a file and costs an edit, so to approve each one first:
[permissions.tools.edit_image]
default = "ask"speech
The generate_speech tool reads a text aloud. It sends the text to an endpoint that speaks the OpenAI Speech API (POST {base_url}/audio/speech), and an audio clip comes back with the call. kage sniffs the clip's type from its bytes, so it is MP3 or WAV whatever the response headers say. kage offers the tool only when [tools.generate_speech] names an endpoint and a model.
[tools.generate_speech]
base_url = "https://speech.example.com/v1"
api_key_env = "SPEECH_API_KEY" # or a key saved for the tool, below
model = "speech-small"
voice = "alloy"The table takes the same keys as the image tables, plus voice, the voice asked when a call names none. The example names no provider because OpenAI lists every model on this route for shutdown on 2027-01-06, so a server that still serves the route is needed. To keep the key out of the environment, save it for the tool with kage auth login generate_speech and leave out api_key_env.
The clip plays where the client plays audio, and it stays in the session: a loaded session replays it. Editors over ACP get an audio block, the TUI shows a [audio/mpeg from the tool, <size>] row, and the desktop shows the clip with buttons to play it and save it. In the TUI, /media open plays the newest clip with the system's player and /media save writes it into the project, unless an image came after it. A call writes a file itself only when it names a path, and it never replaces an existing file. When the file cannot be written, the clip still comes with the call and the result says why.
The server's limits on text length and voices are its own. When it refuses a call, its message reaches the model as written.
The tool counts as a write: plan mode and a read-only session refuse it, as they refuse write, and permission rules name it generate_speech. Each call costs a synthesis, so to approve each one first:
[permissions.tools.generate_speech]
default = "ask"music
The generate_music tool makes one song from a style prompt and, optionally, lyrics. There is no common music API, so kage sends the shape some gateways offer beside their images API: POST {base_url}/music/generations with model, prompt, and lyrics, instrumental and seed when the call names them. kage offers the tool only when [tools.generate_music] names an endpoint and a model.
[tools.generate_music]
base_url = "https://music.example.com/v1"
api_key_env = "MUSIC_API_KEY" # or a key saved for the tool, below
model = "music"The table takes the same keys as [tools.generate_image]. To keep the key out of the environment, save it for the tool with kage auth login generate_music and leave out api_key_env.
The song comes back in the answer's first data entry, as base64 in b64_json, as a data: URI in url, or as a link in url. kage fetches a link only when it is on the endpoint's own host, without the key and without following a redirect. A song that cannot be read, such as one linked on another host, still counts as made: the result says why and gives the link, which anyone holding it can fetch until the server drops it, so the link stays in the session. The seed the server used, and any note it sends, come with the result.
Like a speech clip, the song stays in the session, and /media or the desktop plays and saves it. A call writes a file only when it names a path. A song can take a minute or more; timeout_secs defaults to 180.
The tool counts as a write, as generate_speech does, and permission rules name it generate_music. Each call costs a song, so to approve each one first:
[permissions.tools.generate_music]
default = "ask"environment variables
API keys are read from environment variables:
| Variable | Provider |
|---|---|
ANTHROPIC_API_KEY | Anthropic Claude |
OPENAI_API_KEY | OpenAI |
GEMINI_API_KEY | Google Gemini |
ZAI_API_KEY | Z.AI |
ZAI_CODING_API_KEY | Z.AI and Zhipu AI coding plans |
DEEPSEEK_API_KEY | DeepSeek |
GROQ_API_KEY | Groq |
MISTRAL_API_KEY | Mistral |
CEREBRAS_API_KEY | Cerebras |
XAI_API_KEY | xAI |
OPENROUTER_API_KEY | OpenRouter |
FIREWORKS_API_KEY | Fireworks AI |
MOONSHOT_API_KEY | Moonshot |
KIMI_API_KEY | Kimi for Coding |
XIAOMI_API_KEY | Xiaomi / Xiaomi Token Plan |
CMD_API_KEY | Command Code |
KENARI_API_KEY | Kenari |
The model id picks the provider. Without -m, kage uses provider.default_model when its provider has credentials, then the last model you ran, then the preferred model of the first provider with credentials. When the configured default_model has no credentials, the TUI starts on the fallback and says which model it used instead.
See providers for the full provider list, custom endpoints, and per-provider overrides (base URL, headers, key env var).
directories
| Path | Contents |
|---|---|
~/.config/kage/config.toml | user config |
~/.config/kage/init.lua | trusted Lua config, TUI only (lua config) |
~/.config/kage/lua/ | modules init.lua can require |
<workdir>/.kage/config.toml | project-local config overlay |
~/.config/kage/agents/ | agent definition .md files (agents) |
<workdir>/.kage/agents/ | project agent definitions, loaded once the project is trusted |
~/.config/kage/themes/ | user theme TOML files |
~/.config/kage/plugins/ | Lua plugin scripts |
~/.config/kage/skills/ | SKILL.md skill directories |
~/.config/kage/templates/ | prompt template .md files |
~/.local/share/kage/sessions/ | append-only session JSONL files, one directory per project |
~/.local/share/kage/auth.json | saved provider credentials (0600) |
~/.local/share/kage/mcp-auth.json | OAuth tokens for remote MCP servers (0600) |
~/.local/share/kage/plugin-state/ | per-plugin kage.store JSON files |
~/.local/state/kage/ | session state (state.json) and input history (history.txt) |
~/.local/state/kage/trust.json | trusted project records: gated values plus file hashes |
~/.local/state/kage/trust/blobs/ | approved agent and skill texts, one file per SHA-256 |
~/.cache/kage/models.json | model catalog, refreshed by a running kage or kage models refresh |
~/.cache/kage/models.json.etag | what the catalog server tagged the cached catalog with |
~/.cache/kage/chatgpt-models.json | ChatGPT plan models, written at sign-in and refreshed like the catalog |
~/.cache/kage/providers/<id>.json | the models a custom provider's models_url lists |
XDG_CONFIG_HOME / XDG_DATA_HOME / XDG_STATE_HOME / XDG_CACHE_HOME override the ~/.config, ~/.local/share, ~/.local/state and ~/.cache roots. kage doctor prints the four directories it resolved. 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.
session directories
Sessions are filed in one directory per project under ~/.local/share/kage/sessions/, named for the project's last two path components and a hash of its path, such as kage-personal-1a2b3c4d5e. A session's agents nest under it in <session-id>/agents/. Media the sessions produce is shared in sessions/blobs/.
[sessions]
# What a session's project directory is named for: "repo" (default),
# the repository the working directory sits in, so subdirectories and
# worktrees share one; or "cwd", the working directory itself.
group = "repo"Only the user config sets [sessions], and a change files new sessions only. Sessions recorded before this layout stay in sessions/ itself and keep working.
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. Each skill is also a slash command: /name arguments sends the body as your prompt with the arguments appended, so invoking one is a normal message the model answers with the skill applied. Pass disable_model_invocation: true to keep the /name command out; the body still reaches the system prompt.
A prompt template is a single .md file (frontmatter name, description, argument-hint) whose body becomes a user message with positional substitution. $1, $2 and so on are single arguments, $@ or $ARGUMENTS is all of them joined, and ${@:N:L} is a bash-style slice. Drop files in the directories above. No Lua is required.