Settings
Settings load in this order: compiled defaults → user ~/.kcode/config.toml → trusted <project>/.kcode/config.toml → optional per-launch --config <path> → KCODE_* environment → command-line flags.
Full notes from the app
Each session reads its own project's config only after you trust the project: its sections (the model and effort defaults, the agent loop, compaction, the shell, plugins, language servers) apply to that project's sessions only, read when each session starts, and never to another project's. Its .kcode/skills, .kcode/commands and plugins' skills and commands likewise reach only its own sessions. The app's own settings (the window, theme, keymap, logging, providers, updates, hooks_enabled and the daemon's sections) come only from the user file, --config and the environment. kcode --config alt.toml tries an alternate profile without touching ~/.kcode: the file must exist (a missing or broken path fails the launch instead of being silently ignored), it live-reloads on save like the user file, and when that launch starts the daemon, the daemon boots on the same file, attaching to an already-running daemon applies it client-side only and prints a one-line notice, since a running daemon's config can't be swapped mid-flight. Subcommands (doctor, auth, …) don't accept it. <project> is resolved git-style by walking up from the launch directory: KCODE_PROJECT_DIR if set, else the nearest folder holding a .kcode/ dir or a .git (~/.kcode never counts: that's the user scope), else the cwd, so running kcode from a subdirectory reuses the surrounding project's config, storage, plugins, and sessions, and a git repo inside a folder with a .kcode/ stays its own project. The home folder, a folder above it, / and the folder that holds the data folder are never a project: a start there reads no project settings and keeps nothing there. kcode makes <project>/.kcode/ only when it first keeps something there, so a launch that saves nothing leaves no folder behind. In a git repository a session lists the files kcode keeps for itself there (the project store, /share exports, worktree checkouts, skill state) in the repository's .git/info/exclude, so git add -A leaves them out while the project's config, commands and skills stay visible to git; /doctor names any of them git already tracks, with the line that stops tracking them. Edit the generic knobs via /settings (the fullscreen settings page: layout, grid columns, command/skill dirs), or edit the files directly, kcode watches the user config file and live-applies a subset on save: the theme, the chat view toggles (session_panels.chat.*), the ambient-backdrop shader, the default_model / default_effort / default_output_style defaults (which relay live to the daemon so newly-spawned sessions boot on them), the [keymap] shortcut overrides (rebind any app shortcut and it takes effect on the next key), hooks_enabled (which starts or stops trusted projects' hooks at once), disabled_plugins and [plugin_links] (open sessions load or drop the plugin at once), and each plugin's [plugins.<name>] settings (new sessions get them). A save that changes something posts one notice naming the keys it changed, on up to three lines: those applied now, those new sessions use, and those that wait for a restart. A change made on the Settings page posts none, since the page shows it. A save that leaves the file unparseable posts a warning naming the line and column instead, and kcode keeps the settings it has until a save makes the file read again, whose notice says so; a launch with a broken user file leaves it out, runs on the other layers, and names the line and column in the Settings page, the health report and the log. A file that parses is read key by key: a name kcode doesn't read changes nothing, and a value of the wrong type takes that key's default while the rest of its section applies. The health report, kcode config check, the key's row on the Settings page and a kcode -p run with text output (on stderr) name each one: with the nearest name kcode reads or the type the value needs, never the value. While the user file can't be read, kcode makes no change it would save there (from the Settings page, a picker or a command such as /theme) and says why instead, so nothing changes that a restart would undo; a ⌘⏎ model pick still sets the session's model, and the theme designer still saves its theme file. A change the file refuses all the same posts a notice naming the key. Separately, adding or editing a skill, command, agent-kind or theme file under a configured dir is picked up live by its own file-watcher, in a dir made after launch too. providers, cursor, the command_dirs / skill_dirs dir lists themselves, and deeper lib [section] settings still need a restart; the notice names them. (The models.dev model catalogue is not a restart surface: the daemon re-fetches it on a TTL and pushes updates to clients live.) Run kcode config defaults to print every linked lib's settings at their compiled defaults as TOML (pipe it into config.toml as a starting point).
- compaction-template.md (file)
- The Summary compaction prompt template, editable without recompiling. Resolution: <project>/.kcode/compaction-template.md overrides ~/.kcode/compaction-template.md once the project is trusted (an untrusted project's file is not read); when neither exists the compiled default (a structured, anchored template: Objective / Important Details / Work State{Completed,Active,Blocked} / Next Move / Relevant Files) is written to the user path so it is discoverable. Slots: {{conversation}} (required: the serialised older messages) and {{previous_summary}} (optional: the anchoring block on repeat compactions, empty the first time). Loaded once per session, so edits apply to new sessions (or a restart), not retroactively.
- API keys (env / auth.toml)
- API keys are not a config.toml setting. kcode resolves a provider's credential from its
<PROVIDER>_API_KEYenvironment variable first (env takes precedence, where most users keep keys), then~/.kcode/auth.toml([auth.<id>] api_key = "…", mode 0600), then an OAuth login ([oauth.<id>], same file: the sign-in counts as connected for the /model gate, while a real key always wins over it). Add or update a key (or sign in) interactively in Settings (⌘,) › Providers: a searchable provider list; choosing a row opens a masked prompt (⌘V to paste) that writes auth.toml for you, or, for an OAuth-capable provider, a sign-in method choice first (browser or device code: a ChatGPT sign-in reaches the models ChatGPT lists for the account). Keys live on the settings page rather than a session command because one key serves every session (all-session config). Only the non-secret[providers.<id>]tables live in config.toml. A provider you add keeps its key, when it needs one, in auth.toml under its id; one whose id models.dev lists also reads that provider's environment variable. - Supported providers (whitelist)
- kcode supports a fixed whitelist of the models.dev catalogue's providers, chosen at build time (
provider_catalog::SUPPORTED_CATALOG_IDS): the catalogue itself ships untouched. The list: the six native vendors (Anthropic, OpenAI, Fireworks, DeepSeek, Kimi, MiniMax) plus Kimi For Coding, Baseten, Google (Gemini), Groq, Hugging Face, Llama, Mistral, OpenCode Zen, OpenRouter, Together AI and xAI through the generic OpenAI-compatible connector, plus the Google Vertex pair (listed in Settings › Providers but not runnable yet: Vertex needs a dedicated Google-ADC connector). A catalogue provider outside the whitelist is never listed and gets no client even when its env key is set (an ambientGITHUB_TOKENnever routes a turn to GitHub Copilot) until you add it yourself: any other server that speaks the OpenAI or the Anthropic API, a hosted one, one on your network or one on this Mac, is added as a[providers.<id>]table (seeproviders.<id>.api). Kimi For Coding is first-class: it has its own crate (provider-kimi-coding) over the generic connector, so its existence, endpoint (api.kimi.ai/coding: the global plan; the CN plan atapi.kimi.com/codingis the same subscription, reached by settingproviders."kimi-for-coding".base_url), env var (KIMI_API_KEY), and model metadata live in the code. When models.dev renamed the provider upstream (to kimi-code-plan-global/-cn) every catalogue-derived surface lost it andk3turns failed routing to the renamed ids: now the client, this listing, its models, and the K3 default rule all keep working regardless, with the renamed catalogue ids folded back into it as a metadata overlay. - (full power-user surface)
- This list is curated to the knobs worth knowing. The complete deep-lib section surface (
[agent_loop],[kvstore],[http_client],[shell_client],[event_bus],[scheduler],[file_watcher],[plugin_runtime_lua],[models_dev],[updater], and more) is enumerated with defaults bykcode config defaults(kept honest by a build-time drift test: every documented section is consumed, every consumed section documented).
356 entries · kcode 0.6.5097
| Key | Type | Default | What it does |
|---|---|---|---|
| agent_framework | |||
| agent_framework. | boolean | true | Re-read the agent-kind directories when a file under them changes, so an edited or newly added markdown agent takes effect in the running session instead of only in the next one. On (the default) each session arms a watcher over ~/.kcode/agents/ and <project>/.kcode/agents/, whether or not they exist yet. Set false and no watcher is armed: the registry keeps the set it loaded at session start, and the session skips a watch registration. Restart-only (a deep lib [section] knob). |
| agent_framework. | boolean | true | Honour .gitignore rules while walking the agent-kind directories (~/.kcode/agents/ and <project>/.kcode/agents/: markdown agent definitions, see the Agent Kinds section). A gitignored agent file is skipped. Kinds load at session spawn and, unless agent_framework.hot_reload is off, reload in place when a kind file changes. Restart-only (a deep lib [section] knob). |
| agent_framework. | boolean | true | Honour .ignore rules while walking the agent-kind directories: the .ignore-file twin of agent_framework.respect_gitignore. Restart-only (a deep lib [section] knob). |
| agent_loop | |||
| agent_loop. | integer | 3 | Documented only by its default. Run kcode config defaults for the full table. |
| agent_loop. | integer | 8 | How many concurrent_safe tool calls run at once within one round. When a round yields several calls, the loop resolves permissions in order, then dispatches the safe ones (fs_read, glob, grep, web_fetch/web_search, view_image, memory_search/memory_list, browser_screenshot, read-only shell.*) in a bounded parallel batch (completions stream to the transcript as they land) while everything else still runs one-at-a-time in the model's order; the model-facing tool results are reassembled in call order either way, and a batch abort synthesizes explicit cancellation results for the unfinished calls. 1 (or 0) restores fully sequential dispatch. |
| agent_loop. | integer | 2048 | Cap on tool-call rounds in a single turn before the loop hard-stops with an error (continuation rule 3). Restart-only for the daemon; headless reads it per run. |
| agent_loop. | string | "long" | How long a vendor keeps a session's cached conversation between two provider calls, where the vendor lets kcode choose. Every call requests that the vendor keep the tools, the system prompt and the conversation so far cached, so the next call reads them at the cache price instead of the full input price. long requests about an hour: a session you step away from for a while still reads its conversation from the cache. short requests about five minutes: writing the cache costs less (Anthropic bills 1.25× the input price for it instead of 2×), but any longer pause re-writes the whole conversation at the write price. The tools and the system prompt are always cached for the hour. Anthropic (direct or behind OpenRouter) and Kimi take the choice; the other vendors keep a cache for as long as they choose. Restart-only for the daemon. |
| agent_loop. | integer | 600 | The longest a provider call may go without showing anything: no reply text, reasoning or tool call. Keep-alives and usage counts do not count, so this ends a server that answers every wait with a keep-alive and never with the answer, which the stall guard (agent_loop.provider_stall_timeout_ms) cannot see. It is also the one limit on a one-shot (non-streaming) call, which shows its whole answer at once. Only the time spent waiting on the provider counts. Before the reply starts it retries through agent_loop.provider_retry like a stall, and when the attempts run out the turn ends with 'Provider sent no output for <limit>, the agent_loop.provider_no_output_limit_secs limit (attempt n/m). Resend to retry.': for a one-shot call, 'Provider did not answer within <limit>, …'; after the reply has started it cuts the reply off, and the loop carries it on in a new round, as for a stall. 0 turns it off. Restart-only for the daemon. |
| agent_loop. | { max_attempts, initial_delay_ms, max_delay_secs, jitter } | 6 attempts, 10s initial, 60s cap, equal jitter | The retry schedule for an overloaded vendor: a 529, a 503, or an error the vendor names 'overloaded'. An overload takes tens of seconds to clear, so this schedule tries more often and waits longer than agent_loop.provider_retry: from 10 s doubling to 60 s, each wait between half and all of its step. One attempt count runs across both schedules, and each failure is judged against its own schedule's max_attempts. A wait the server names is kept as given, as for agent_loop.provider_retry. A table that sets only some keys keeps these defaults for the rest. Restart-only for the daemon. |
| agent_loop. | integer | 10000 | Documented only by its default. Run kcode config defaults for the full table. |
| agent_loop. | string | "equal" | Documented only by its default. Run kcode config defaults for the full table. |
| agent_loop. | integer | 6 | Documented only by its default. Run kcode config defaults for the full table. |
| agent_loop. | integer | 60 | Documented only by its default. Run kcode config defaults for the full table. |
| agent_loop. | { max_attempts, initial_delay_ms, max_delay_secs, jitter } | 4 attempts, 1s initial, 30s cap, full jitter | How the loop retries a provider call that failed before its reply started: a request-time error (a 429, a 5xx, a dropped connection), a stall (agent_loop.provider_stall_timeout_ms), a call that showed nothing within agent_loop.provider_no_output_limit_secs, or an error that arrives after nothing but thinking, usage counts and keep-alives. A call whose reply has started (reply text or a tool call) is never sent again, so no text is ever shown twice: when such a reply is cut off (the connection lost, the stream broken, or a stall) the text that arrived stays in the chat and the history, and a new round tells the model, with <cp:reply-cut-off>, to go on from it. The cut-offs in a row count against the failure's schedule as retries do, and the working strip shows them the same way. Thinking starts no reply: it shows as it comes, and a retried call's thinking follows the failed call's. The provider judges each failure (its classify_error): a quota, billing, sign-in or bad-request error is not retried, except a ChatGPT plan limit that says when it resets, which is waited for like any server wait; an overloaded vendor falls under agent_loop.provider_overload_retry instead; a server that sends x-should-retry has the last word, as it does in Anthropic's and OpenAI's own SDKs; the loop's own stall and no-output errors always retry. When the server names a wait: a Retry-After header, a wait in the error message, Google's retry delay, a plan limit's reset time, or on a 429 the reset time of the rate limit that ran out, the loop waits exactly that long, up to agent_loop.provider_wait_limit_secs; otherwise it waits from initial_delay_ms, doubling up to max_delay_secs. max_attempts counts every call, the first one included. A table that sets only some keys keeps these defaults for the rest. While a retry waits, the chat's working strip reads 'Provider error — retry n/m in <wait> (reason)' instead of a bare spinner, or 'Provider not responding — …' when the provider sent nothing at all, counting the wait down and reading 'now' once the retried call is out, and headless ndjson emits a provider_retry line whose stalled field is true for a call that sent nothing; when a retried call fails for good the turn ends with 'Provider still failing after N attempts: <error>. Resend to retry.' Context-overflow errors are excluded: they go to compaction recovery. Restart-only for the daemon. |
| agent_loop. | integer | 1000 | Documented only by its default. Run kcode config defaults for the full table. |
| agent_loop. | string | "full" | Documented only by its default. Run kcode config defaults for the full table. |
| agent_loop. | integer | 4 | Documented only by its default. Run kcode config defaults for the full table. |
| agent_loop. | integer | 30 | Documented only by its default. Run kcode config defaults for the full table. |
| agent_loop. | integer | 300000 | The stall guard: the longest a streamed provider call may send nothing at all before it is treated as failed. Provider clients deliberately carry no whole-request timeout (it would abort long SSE streams) so without this a server that accepts the request and then goes quiet hangs the turn forever (the 'everything looks stuck' case). Anything the server sends restarts the clock, a keep-alive included (DeepSeek's : keep-alive lines while a request waits in its queue, OpenRouter's : OPENROUTER PROCESSING, Anthropic's ping) so a server that is still working is not cut off; agent_loop.provider_no_output_limit_secs ends one that sends keep-alives and never the answer. Before the reply starts a stall retries through agent_loop.provider_retry (no reply text yet, so no duplication), and when the attempts run out the turn ends with 'Provider silent — no data for Ns (attempt n/m). Resend to retry.'; after the reply has started a stall cuts the reply off, and the loop carries it on in a new round (see agent_loop.provider_retry). A one-shot (non-streaming) call gets its whole answer at once, so this guard does not watch it: the no-output limit bounds it instead. While any turn is provider-silent ≥3s with no tool mid-run, the working strip appends a live '· waiting Ns' clock, and each settled turn's footer names the vendor's share: '▣ model · elapsed · provider 24.2s ×3 · ttfb 1.2s', where the time to first byte runs to the first thing the server sends that is not a keep-alive (headless: per-round provider_round ndjson lines). 0 disables the guard. Restart-only for the daemon. |
| agent_loop. | integer | 300 | The longest wait a provider may ask for before a retry. A 429's Retry-After (or a wait the error message names, or the time a ChatGPT plan limit resets) is kept exactly as given, never cut short to the retry schedule. A wait longer than this ends the turn at once, rather than leaving it silent for hours: 'The provider set a wait of <wait> before another try, longer than the <limit> limit set by agent_loop.provider_wait_limit_secs. Resend the message once the wait is over. The provider said: <error>' 0 = no limit: sit through any wait. Restart-only for the daemon. |
| agent_loop. | boolean | true | Documented only by its default. Run kcode config defaults for the full table. |
| agent_loop. | integer | 10000000 | The request size past which kcode takes the pictures the model has already seen out of the conversation, so a long session full of screenshots stays quick to send. Text counts by its length and a picture by its encoded size. kcode also takes them out whenever the vendor's cache of the conversation has gone cold anyway: the time agent_loop.prompt_cache_retention names (an hour, or five minutes) has passed since the last call, or another model now answers, and after a compaction, since then taking them out costs no extra cache read. A picture the model has not seen yet always stays. Each one taken out leaves a short note naming its file and size, so the model can look again with view_image, or read_pdf for a PDF's page, while the file is there. The removal is for good: the chat still shows the picture. 0 takes none out for size. Restart-only for the daemon. |
| agent_loop. | boolean | true | Documented only by its default. Run kcode config defaults for the full table. |
| agent_loop. | boolean | true | Append a <cp:time utc="…" local="…"> stamp to every message kcode authors: the user's turn, each tool result, each channel injection. A model has no clock, so without this it cannot tell whether the last message was thirty seconds or three days ago, how long a build took, or that it is 2am where you sit; stamping each message as it is written turns the history itself into the record of elapsed time. A tool result's stamp also carries duration_ms (that call's own wall time) and a user-role message's stamp carries origin (typed/queued/channel/nudge/plugin/hook/trigger, a hook's prompt adding hook, the hook's name, and a kcode trigger's text adding trigger, the trigger's name). Written once per message and never re-stamped, so the provider's prompt cache still holds. Assistant messages are never stamped. The stamp is hidden from the chat transcript and the markdown export. Restart-only for the daemon. |
| agent_session | |||
| agent_session. | integer | 5 | Time allowed for an interrupted turn to finish saving, and for the session's background subagents to remove or keep their checkouts, when its session stops or the app quits. Shutdown cancels the turn but drains its stream through the final save; all sessions drain concurrently without blocking database IO. Completed exchanges are also checkpointed during a long turn. Partial visible replies and results from completed tools survive a graceful stop. If the deadline expires, the last completed checkpoint remains; force-killing the process cannot guarantee the latest unsaved text. Restart-only for the daemon. |
| agents_md | |||
| agents_md. | boolean | true | Whether the system prompt's project-context walk reads the Claude Code rules directories (~/.claude/rules/ at the user-global layer and <dir>/.claude/rules/ at every project level walked inside the project) in a git repository the folders from the opened one up to the repository's root, outside one the opened folder alone: once you trust the project. On by default (the .claude/rules/ convention is shared with Claude Code). Each rules directory is read as Claude Code reads it: every .md file in it and its subfolders, linked folders of shared rules included, hidden folders such as .git passed over. In a project's own AGENTS.md, .claude/rules/, .kcode/AGENTS.md and .kcode/rules/, a link is followed only while it stays inside the project, and one that leads out is not read, the health report (/doctor, kcode doctor) names it, keep shared rules in <data dir>/rules/ or ~/.claude/rules/, where every link is followed. A file saved as UTF-16 with a byte-order mark is read as it is; one in another encoding is read with the bytes that aren't UTF-8 replaced, and one kcode can't open is left out: the health report names each, and none stops a session. Set false and kcode reads only AGENTS.md at each level, <data dir>/rules/ and <project>/.kcode/rules/ (.kcode/AGENTS.md and .kcode/rules/ only in a trusted project). A project's .claude/rules/ are still listed in its trust dialog while this is off. CLAUDE.md is never automatically loaded, even with interop enabled or when AGENTS.md is absent. Useful when your Claude Code rules should not steer kcode, and set by make fresh (KCODE_AGENTS_MD__CLAUDE_INTEROP=false) so a developer's rules never reach a fresh-user run. Restart-only (a deep lib [section] knob; sessions read it at spawn). |
| browser_host | |||
| browser_host. | integer | 30 | The per-call cap on every CDP (Chrome DevTools Protocol) round trip: a wedged page must not hang a browser_* tool forever. Restart-only. |
| browser_host. | integer | 300 | How long browser_click waits for the click to start loading a page, in milliseconds. A page that starts loading is waited for as browser_navigate waits, up to browser_host.navigate_load_timeout_secs; a click that loads nothing returns after this wait. Restart-only. |
| browser_host. | string? | none | An explicit Chrome-family browser binary for the browser tools: wins over discovery and the downloaded bundle (a CHROME_PATH env var sits between this and discovery). Unset = discover Chrome, Chromium, Edge, Brave, or Arc. Restart-only. |
| browser_host. | integer | 15 | How long browser_navigate, or a browser_click that starts loading a page, waits for the page to load before returning anyway: a slow page doesn't fail the navigate, the wait just bounds how long the call blocks before a following browser_evaluate/browser_screenshot runs against whatever has loaded. Restart-only. |
| browser_host. | integer | 32768 | How much of a page's text browser_navigate and browser_click return to the model, in bytes. The rest stays on the page, and the result says how much was left out and the browser_evaluate call that returns the next part. Restart-only. |
| browser_host. | string | "sandbox" | Which browser profile sessions run on: sandbox (a fresh ephemeral profile per browser launch, wiped with it) or the name of a persistent profile under <data>/browser-profiles/<name>/, created on first use and kept across sessions (letters, digits, -, _). The agent's browser navigations, clicks and fills run without a prompt, so in a saved profile they act with the sign-ins it holds. Restart-only. |
| browser_host. | string? | <data>/screenshots | Where browser_screenshot saves each capture as <session>-<stamp>.jpg: the result names the file, the chat shows the picture inline, and the model can re-read it with view_image. Restart-only. |
| codevex_local | |||
| codevex_local. | string | "auto" | Local embedding backend: auto prefers Metal on macOS and falls back to CPU when unavailable; cpu explicitly uses the private CPU pool; metal requires a GPU. Both keep source and queries local. Backend selection and fallback are logged. Restart-only. |
| codevex_local. | integer | 2 | Private CPU inference worker pool size, clamped to 1–8. Does not change the global Rayon pool or control Metal GPU parallelism. Restart-only. |
| codevex_runtime | |||
| codevex_runtime. | boolean | true | Register native sem_search for project sessions. Indexing and local model loading are lazy on first query, which downloads the pinned, hash-verified ~91 MB MiniLM model when it isn't there yet. Source and queries are never uploaded. Restart-only. |
| codevex_runtime. | integer | 4096 | Maximum code bytes per retrieval chunk (256–16384); longer declarations split at UTF-8/line boundaries. Model token windows cover long projections without silent truncation. Changing it rebuilds the cache. Restart-only. |
| codevex_runtime. | integer | 100000 | Maximum source chunks in a semantic generation, bounding exact cosine ranking. A capacity failure names the exhausted resource, file, required amount and limit. Restart-only. |
| codevex_runtime. | integer | 262144 | Maximum individual source file size for semantic indexing; larger files are skipped and counted. Restart-only. |
| codevex_runtime. | integer | 10000 | Maximum eligible source files per checkout index. Aggregate limits fail the refresh and preserve the old generation. Restart-only. |
| codevex_runtime. | integer | 50331648 | Bound on overlapping source/comment projections materialized for semantic indexing. Restart-only. |
| codevex_runtime. | integer | 33554432 | Aggregate source-read budget per semantic refresh/query verification. Exceeding it aborts refresh rather than publishing incomplete membership. Restart-only. |
| codevex_runtime. | integer | 100000 | Maximum entries examined during semantic source discovery. Restart-only. |
| codevex_runtime. | integer | 1500 | Bounded wait for cold semantic-index readiness before returning explicit not-ready status. Restart-only. |
| codevex_runtime. | integer | 4 | Maximum resident per-checkout semantic indexes; least-recently-used entries are evicted and their refresh cancelled. Restart-only. |
| codevex_runtime. | integer | 32768 | Maximum serialized sem_search response bytes; source previews are truncated and marked. Restart-only. |
| codevex_runtime. | integer | 4096 | Maximum UTF-8 bytes in a semantic-search query. Restart-only. |
| codevex_runtime. | integer | 20 | Maximum sem_search matches; the tool defaults to min(8, this limit). Restart-only. |
| codevex_runtime. | integer | 536870912 | Bound on each complete serialized semantic index in project SQLite. Oversized writes/reads fail rather than consume unbounded memory. Restart-only. |
| codevex_runtime. | integer | 60 | Maximum queue/inference/search time for one semantic query. Restart-only. |
| codevex_runtime. | integer | 30 | Query-time age threshold for refreshing an index, alongside existing file-change invalidation. No idle scan loop. Restart-only. |
| codevex_runtime. | integer | 1800 | Maximum preparation time for a semantic refresh before preserving the last-good index. A complete SQLite commit already started is allowed to finish. Restart-only. |
| (top level) | |||
| command_dirs | string[]? | ["~/.kcode/commands"] | Markdown command source directories. Supports ~ and $HOME expansion. Each *.md file becomes a client-side /<name> slash command whose body is the prompt, with $ARGUMENTS / $1,$2… substitution (see /commands). Unset resolves to ~/.kcode/commands plus the session's own <project>/.kcode/commands once you trust the project; setting this key replaces the list entirely, and a project's config.toml may set it for that project's sessions. A command file (or a subdirectory of them) symlinked into a configured dir is followed (command_framework.follow_symlinks, on by default), so a centrally-managed setup that symlinks individual commands in works. Adding or editing a command file under a configured dir is picked up live by a file-watcher (no restart), in a dir made after launch too; changing this dir list itself takes a restart in the user config, and in a project's config.toml applies once that project's sessions have all stopped and one starts again: a project's sessions share one set of commands, made when the first starts. Plugin bundles contribute commands separately: <plugin>/commands/*.md under the plugin roots load after these dirs (a configured command wins a name collision with a bundle's); setting this key does not affect the plugin channel. GPU build only. |
| default_effort | string? | none | Default reasoning effort for new sessions. Unset means Highest supported by model, resolved again when the session switches models. Set minimal, low, medium, high, xhigh, or max to override that policy; the value is clamped to the current model's accepted levels and omitted for models without an effort control. Settings → General → Default effort cycles from highest supported through the named levels and back. The setting persists and relays live to the daemon for new sessions; saving this key in config.toml does the same. Existing sessions keep the config default they started with. /effort <level> overrides it for one session; /effort default clears that session override. |
| default_model | string? | none | Default model every new session boots on: a model id, which runs on the first connected provider that lists it, or <provider>:<model>, which runs on that provider (the pickers write this form) (unset ⇒ new sessions start on the first [[models]] pin, else with no model until the user picks one in Settings: there is no compiled-in default. In the app, a message sent from a session with no model opens the /model picker and is sent once a model is picked; a turn that still runs with no model stops before it reaches the provider, naming /model and this picker in the app and --model <id> for kcode -p, or, when config.toml can't be parsed, that file with its line and column, since a default set there isn't in use. Connecting a provider, a key or a sign-in, while this key and every [[models]] pin are unset opens this picker at that provider's models, and a newly chosen default also reaches every open session that has no model). Set it from the GPU Settings page's General → Default model picker (a searchable list of every provider's models, the keyed providers first, then the unkeyed ones under Provider · no key sections, folded as in /model: every provider section starts closed but the one the current default is on, with no default, the one provider you have a key for, or none when several or none have one, and a search reveals matches in every section; picking a model there opens that provider's key prompt first and sets the default once it lands; its first row, No default, unsets the key and says what new sessions then start on, and the settings row reads (none) while the key is unset; its footer names its keys, ↩ Choose, ⌘D Favorite, as in /model): the pick persists here and relays a live SetDefaultModel to the daemon, so newly-spawned sessions use it without a restart. A direct edit of this key in config.toml relays the same live SetDefaultModel on save. Override a single session per-turn with /model <id>, or a whole launch with kcode --model <id> (applies to sessions that window spawns and to the session a kcode --resume <id> or -c launch opens; the session keeps the model across restarts, like /model). GPU build only for the picker; the key is read on every build. |
| default_output_style | string? | default | Active output style: selects the tone/format instructions appended to the agent's system prompt as an ## Output style section (augmenting, not replacing, kcode's curated style). Accepts a built-in name or a plugin-bundled style's name, in any case; None/unset or an unknown name falls back to the default built-in, and /doctor names an unknown one (output-style.unknown). Change with /output-style: the pick persists here and relays a live SetDefaultOutputStyle to the daemon so newly-spawned sessions use it without a restart; editing this key in config.toml directly relays the same on save. Live sessions keep the style they were built with. |
| disabled_plugins | string list | [] | Plugin names switched off: a listed plugin is skipped at session stack build on every path (discovery, hot reload, manual load), its own discovery outcome, mirroring the project policy blocklist, reported as your choice rather than a load failure. Written by the Settings › Plugins Enabled toggle (a read-modify-write list edit, so two project windows never clobber each other's entries); hand-editing works too. Its own top-level key, never [plugins.<name>] enabled, which would collide with a plugin's own settings vocabulary. A listed plugin adds no commands, skills, agents, output styles or themes either, built-in bundles included. User scope; a flip in Settings, or a hand edit of config.toml, applies to open sessions at once: only an output style already in an open session's system prompt stays until that session restarts. |
| disabled_tools | string list | [] | The tools of kcode's own you turned off: names such as web_fetch or bash. A turned-off tool is left out of the tools each session offers the model, the session's system prompt names it with a line asking the model not to call or suggest it, and a call the model makes to it anyway is refused unrun. Written by the switches in Settings › Tools, one per tool, with the first sentence of what each does; hand-editing works too. A change, from Settings or a hand edit of config.toml, applies at every session's next turn: only the system prompt line waits for a new session, a resume or a reload. Only kcode's own tool names count: a plugin's or an MCP server's tool is never turned off by this list, even one with the same name, and /doctor names each entry that isn't one of kcode's tools with the closest tool name (config.disabled-tools). A trusted project's .kcode/config.toml can set its own list, which takes the place of yours in that project's sessions, kcode -p included: Settings › Tools doesn't change those sessions, and a change to the project's list reaches its sessions that start or resume after it. |
| hooks | [[hooks]] array (a project's, or your own webhook-only ones) | none | Project automation: declare hooks in <project>/.kcode/config.toml and kcode injects an input line into a session of that project when something happens, no plugin required. Each [[hooks]] entry: name (required: the hook's identity in notices, /control, and reloads), on = fs:file-changed (optional filter glob over project-relative paths; gitignore-respecting, kcode's own .git/.kcode writes never fire) | timer:cron (requires schedule: six fields, seconds first, second minute hour day month weekday, as in 0 0 9 * * 1-5 for 09:00 local time on weekdays, read as eventsource_timer.crons are; weekdays count as in crontab, 1 Monday … 6 Saturday and 0 or 7 Sunday, or by name (Mon-Fri), with an optional seventh for the year, or @hourly, @daily, @weekly, @monthly or @yearly; a five-field crontab line is skipped with a notice that gives its six-field form) | app:turn-started / app:turn-finished / app:turn-error / app:turn-interrupted-user / app:turn-interrupted-agent (session lifecycle in that project; each turn end fires one: finished, failed, stopped with Esc, or stopped by another session's agent; a turn ended by its own session stopping fires none. The fire data carries {session_id, project_path, title} (the session's project folder and its own title, null when it has none) app:turn-error adds summary, the error the turn ended on, and app:turn-interrupted-agent adds by_session_id and by_name: the session whose agent stopped the turn, by id and by its title or folder name) | app:waits-changed (what a session of the project waits on you for changed: a permission card or a question opened, or was answered or dropped; the fire data is core.app.waits-changed's {session_id, waits} with the session's project_path and title, and a hook's own turn fires none) | app:attention-changed (a session of the project changed how it wants your attention: it went idle, started working, needs your input or shows an error; the fire data is core.app.attention-changed's {session_id, from, to} with the session's project_path and title, and a hook's own turn fires none) | worktree:create / worktree:remove (a worktree checkout of this project came into existence with a session on it, or was deleted: /worktree new and the agent's spawn_worktree_session fire create (adopt does not: that checkout already existed); /worktree remove, the clean stop-time sweep, and the post-merge sweep fire remove. Declared in the base project's config and fired on the base project's stack, so session = "active" targets the base project's sessions. The fire data carries {session_id, slug, branch, path, project, project_path, env} plus slot/port/domain when the row has a slot, project_path being the base project's folder, env being the base project's rendered [worktree.env] overlay and port its port_base + slot, as the worktree's shell has them, and a prompt line splices any of it via {{session_id}}, {{slug}}, {{port}}, {{env.KEY}} etc., so prompt = "run: createdb app_{{slug}}" names the real checkout; this is how projects script the heavy isolation kcode doesn't own: create/drop a database, compose up/down. filter/schedule are validation errors here) | webhook:<name> (fired by an external trigger of the same name: kcode trigger <name> … or any ExternalTrigger sender, or an authenticated POST to the loopback webhook listener (session_daemon.webhook_*), fires every webhook hook declared for it, through the normal injection + concurrency path. A kcode trigger's text reaches each hook: a prompt takes it in place of {{text}}, or as its own paragraph after a prompt without {{text}}, and a run line takes it as its arguments; kcode trigger --session <title> runs the hooks in that session instead of their own session. The listener's body never reaches a session: the hooks it fires run their lines as written. When the project declares no webhook hook for it, the trigger's text injects into the target session directly, under a trigger · <name> label and stamped origin="trigger", never in place of declared hooks, whether a rate cap drops a fire or the hooks can't run: off, untrusted, held for trust or with no session open, the trigger runs nothing and says why), exactly one of run = "/name" (runs as your /name does, the name matching in any case, with a kcode trigger's text after it for a webhook: hook and no text otherwise: a skill first, started with its script, state folder, placeholders and allowed-tools, then a markdown command, whose body runs with that text as its arguments; either runs on its model as the /name does, and a model no connected provider serves is named in a notification and the session's used; kcode's own commands like /theme, plugin commands, a skill marked user-invocable: false and an unknown name drop the fire with a notification saying why; the line names only the command, with no arguments of its own) or prompt = "…" (injected as written, with a worktree hook's placeholders or a kcode trigger's text filled in) (unless the entry is webhook-only) and optionally webhook = "https://…" (the daemon POSTs to the URL on every fire, fire-and-forget over one pooled client per project, and one for your own hooks, a 10 s timeout by default, project_hook_runtime.webhook_timeout_secs, never fatal: a failure or non-2xx answer is named in a hook notice, one per hook and URL counting the failures, the declared URL shown without its query; loopback/private hosts allowed; composes with run/prompt or stands alone; a webhook-only entry never touches a session and rejects session/concurrency) with optional webhook_headers = { Title = "…" } (header names to text; Host, Content-Length, Transfer-Encoding and Connection are kcode's) and webhook_body (text, sent as plain text, or a table or list, sent as JSON; unset, the POST carries the JSON fire record {hook, kind, source, intent, data, project, fired_at}, and a set body's Content-Type is added unless a header names one). The URL, each header value and each text in the body take {{name}} placeholders filled from the fire: {{hook}}, {{kind}}, {{project}} (the folder's name), {{project_path}}, {{fired_at}}, {{data}} and {{data.<field>}} (a number names a list's item), as in webhook = "https://ntfy.sh/my-topic" with webhook_body = "{{project}}: turn failed in {{data.session_id}}". A name kcode doesn't fill or a {{ with no }} keeps the hook from loading with a notice naming the name you likely meant. A value put in the URL is percent-encoded, and the scheme and host must be written out before any placeholder; a missing value or null fills nothing; in a JSON body a string that is one placeholder alone keeps the value's type (a number stays a number, a missing one is null). A value put in is never read for placeholders, session = active (default: the project's most-recently-active live session; none live ⇒ the fire is dropped with a notification) | new (spawns a fresh session titled after the hook) | title:<t> (the live session with that title), concurrency = drop (default: suppress while a previous fire's injected turn is incomplete) | queue | replace (supersede the pending, never a running turn) | parallel, and enabled (default true; false keeps the entry declared but inert: a disabled entry never blocks an enabled one of the same name, while of two enabled entries of one name the later is skipped with a warning). Hooks never interrupt a running turn (fires wait for the next turn boundary) and a hook-injected turn never fires app: hooks (no chaining). Every fire lands a <cp:hook-fired> row on /control, and the line a hook injects (its prompt, or what its run line expands to) shows in the chat under a hook · <name> label, never as your message (the ↑ your-last-message jump skips it), reaches the agent stamped origin="hook" with the hook's name, and is named in both session exports; every drop (no target, a run name a hook can't run, a rate cap) and every invalid declaration lands in the notification center as a ⚠ Hook notice that names the hook (by its name, or as unnamed hook #N, numbered from 1 as the trust dialog numbers it) and says what happened to it: it won't run, didn't run a fire, is held or stopped, then why, in whole sentences. The triggers_framework.rate_limits caps hold each hook on its own, counting only the fires it matches, a saved file no hook's filter matches counts toward nothing: per_minute (default 60) holds every fire, while per_turn (default 50, counted from the latest turn in the project) and the start_new_cooldown_secs gap (default 30) hold only a hook that starts turns, so a webhook-only hook answers to per_minute alone. A timer hook's schedule is checked against the caps when it loads: one that would fire twice inside the gap (for a hook that starts turns) or more than per_minute times in a minute is skipped with a notice naming the gap or the limit and its setting, and a schedule that passes is never cut, so two timer hooks due at the same moment both run. A fire a cap drops adds one Hook notice per hook and cap that names the hook, the limit and its setting; each later drop rewrites that notice with the count ('skipped 3 fires') instead of adding a row. Gated twice: the global hooks_enabled opt-in above (Settings › Advanced › Project hooks, live) AND project trust, the trust dialog lists each declared hook by name, and adding a hook to an already-trusted project, or changing what one does, re-prompts with that hook listed (a change marked). Saving the project config live-reloads the set (added hooks start, removed stop, changed restart; unchanged keep their in-flight state). A project's hooks start only while the whole project is trusted. A save that adds or changes a hook your trust doesn't cover holds just that hook (a queued fire of it included) with a Hook notice, while the project's other hooks keep running; the window shows the trust dialog for the project, and the hook starts once you trust it. Your own hooks: a [[hooks]] array in ~/.kcode/config.toml declares hooks that run for every project and only post a webhook; webhook is required, on is an app: or worktree: event, and run, prompt, session, concurrency, filter or schedule keeps a hook from loading. Neither hooks_enabled nor project trust holds them, since they start no turn. Their URL, headers and body may also name {{secret.<name>}}, a value you keep in ~/.kcode/auth.toml under [hook_secrets] (slack = "T000/B000/XXXX", written by hand), read at each fire, so a secret you save reaches the next fire; it goes in the URL as written, not percent-encoded, and logs and notices never show it. A secret that isn't there keeps the fire from posting, and a Hook notice names it. A project's hooks can't name a secret. {{project}} and {{project_path}} are the project the event happened in: for a worktree: event, the base project. Your hooks start with kcode, a save of the file runs what it says at once, a problem with one is a Hook notice of the app rather than of a session, a hook's own turn fires none of them either, and /debug lists them as ~/.kcode/config.toml (user hooks). For example on = "app:turn-error" with webhook = "https://hooks.slack.com/services/{{secret.slack}}" and webhook_body = { text = "kcode failed in {{project}}: {{data.summary}}" }. |
| hooks_enabled | bool? | false | Global opt-in for project automation hooks (the [[hooks]] array below). Off by default, no project's hooks compile or fire until you turn it on (your own webhook-only hooks in this file don't need it): the Project hooks switch in Settings › Advanced › Project hooks (search "hook"), or hooks_enabled = true in ~/.kcode/config.toml. Either applies at once, with no restart: on, the hooks of every trusted project with a live session start; off, every project's hooks stop and their queued fires are dropped. It is one switch for all your projects, read only from your own settings: a project's .kcode/config.toml can't turn it on. A top-level key rather than a [hooks] table because the project-scope declaration form is a [[hooks]] array at the same TOML path, and one key can't be a table in one file and an array in another. Hooks additionally require the project to be trusted: see the Permission Modes section's Project trust entry. While it is off, the trust dialog says a project's hooks won't run, and a trusted project that declares hooks gets a hook.off review finding in its /doctor report naming the switch, with a button that opens it; ignore the finding if you don't want them to run, and it comes back when a hook is added. |
| keymap | map? | (built-in defaults) | GPU client mode: a top-level [keymap] block that rebinds Mission Control's app-level keyboard shortcuts without a recompile, an action = chord table where the value is a single chord string (tasks = "cmd-y"), a list of chords (text_size_increase = ["cmd-=", "cmd-+"]), or false to unbind the action entirely (new_session = false). A chord is cmd- ctrl- alt- shift- prefixes (any order, any case, friendly aliases command-/super-/meta-/control-/option-/opt- accepted, and + works in place of -, so Cmd+Shift+N is cmd-shift-n) plus one key: e.g. cmd-shift-], ctrl-b, cmd-- (⌘ + the - key), cmd-,. A key is one character, a named key (enter, escape, space, tab, backspace, delete, up/down/left/right, home, end, pageup, pagedown, f1–f35), or a punctuation key's name (equal, plus, minus, comma, period, slash, backslash, semicolon, quote, backquote, bracketleft, bracketright); any other key is refused. An override replaces that action's default chords; unlisted actions keep their built-in defaults. The rebindable action names and their defaults: new_session (⌘N), switch_session (⌘K, the historical sessions), toggle_sidebar (⌘⇧B, collapse the Sidebar's rail (280 px, at most a third of the window) to a 48 px dot strip or expand it; saved with the workspace; also available as Collapse or expand sidebar in the command palette), jump_to_session_1…jump_to_session_9 (⌘1–9, jump to the Nth session in the order the layout shows, preserving Sidebar/Tabbed layout; maximize from Grid: each slot rebindable on its own), focus_next_session (⌘⇧], move the maximized focus, or the grid's selection, to the next session or browser tile shown), focus_prev_session (⌘⇧[), mission_control (⌘M, the way home to the grid), open_selected_tile (↩, open the tile selected in the grid, as a click on it does), tile_actions (⌘↩, the context menu on the selected tile), move_tile_later (⌘⌃], move the selected tile, tab, or Sidebar row one place later), move_tile_earlier (⌘⌃[), command_palette (⌘P), notifications (⌘⇧N, the notification center), stats (⌘⇧S, the focused session's stats dashboard), tasks (⌘T), note_composer (⌘I, the note composer in the maximized session's prompt), file_for_later (⌘⌥I, save the current draft as a note and clear it after saving), notes (⌘⇧I, the project notes overlay), settings (⌘,, the settings page), cheatsheet (⌃B, this shortcut list), jump_to_last_message (⌘J), text_size_increase (⌘=/⌘+), text_size_decrease (⌘−), text_size_reset (⌘0). Esc (stop turn / back out) and Ctrl-C (unconditional cancel / exit) stay built-in and are not rebindable in v1: they are the fixed escape hatches. A key that names no known action, a chord that can't be used, a value that is not a chord, a list or false, or two actions colliding on one chord (the later one is dropped, your override wins over an unchanged default) is named in a warning toast at launch and on each save, and in the global health report; every binding that resolved cleanly still applies, and an action none of whose chords can be used keeps its default. kcode config check names the same problems from a terminal. Editing the block in config.toml re-applies it live on save: a rebind takes effect on the very next key, no restart. The ⌃B keyboard cheatsheet shows your effective bindings, so a rebound chord appears there too (an unbound action shows —); only Esc/Ctrl-C are listed fixed. GPU build only. |
| models | ModelEntry[]? | none | Catalogue of selectable models. Each entry: { id, display?, provider }. Drives /model autocomplete and /models listing. An OpenAI fine-tune pinned here (id = "ft:gpt-4.1-2025-04-14:my-org::abc", provider = "openai") gets the tools, vision, context window and token counting of the model it was trained from; its price shows, because OpenAI bills fine-tunes at their own rates. |
| skill_dirs | string[]? | ["~/.kcode/skills"] | Skill source directories. Same shape and resolution as command_dirs (unset ⇒ ~/.kcode/skills plus the session's own <project>/.kcode/skills once you trust the project; setting the key replaces the list, and a project's config.toml may set it for that project's sessions). Each skill becomes a /<name> slash command surfaced by SkillRegistry (see /skills). A skill file or skill directory symlinked into a configured dir is followed (skill_framework.follow_symlinks, on by default), so a setup that symlinks individual skills in works. Adding or editing a skill file under a configured dir is picked up live by a file-watcher (no restart), in a dir made after launch too; changing this dir list itself works as command_dirs's does. Plugin bundles contribute skills separately: <plugin>/skills/*.md under the plugin roots load after these dirs (a configured skill wins a name collision with a bundle's); setting this key does not affect the plugin channel. |
| theme | string? | kcode-dark | Display theme name. The GPU client resolves it against its theme catalogue: the bundled kcode-dark / kcode-light / kcode-high-contrast / kcode (mode-following) / one-dark / dracula / tokyo-night / github-light / solarized-light, any ~/.kcode/themes/*.ron|*.json, plus any plugin-bundled <plugin>/themes/*.ron|*.json, falling back to kcode-dark when unset or the name isn't in the catalogue. The first four are Wingman's wingman-dark / wingman-light / wingman-high-contrast / wingman under kcode's names; a config still carrying a wingman-* name is rewritten to the kcode name on load. Change it live with /theme (picker on no-args, /theme <name> to set directly). Editing this key in config.toml also re-applies the theme live on save, diff-gated so it never clobbers an in-app /theme pick. |
| theme_mode | string? | system | Which mode a theme resolves at: "dark" or "light" to lock one, "system" to follow the OS appearance and re-theme live when it changes, or "document" to use whatever the theme file itself declares. Only matters for kcode and a theme that declares both modes (a colour authored as (dark: …, light: …)); a theme with one look renders the same either way, so pick another theme to change its look. No Settings row writes this key; picking the kcode theme sets it to system, so that theme always follows the Mac when you pick it. Live-reloads on a config.toml save, like theme. GPU build only. |
| command_framework | |||
| command_framework. | boolean | true | Follow symlinks encountered while walking a command_dirs directory. On by default so a centrally-managed setup, where individual command files (or subdirectories) under ~/.kcode/commands are symlinks into a shared repo, resolves to the real files. A symlinked root command dir is followed regardless of this flag; it governs symlinks met during the walk. Restart-only (a deep lib [section] knob). |
| command_framework. | boolean | true | Documented only by its default. Run kcode config defaults for the full table. |
| command_framework. | boolean | true | Documented only by its default. Run kcode config defaults for the full table. |
| compaction | |||
| compaction. | float | 0.85 | The share of the effective input budget (window − output reservation − safety buffer) at which an automatic compaction fires, unless compaction.auto_compact_tokens is smaller: the trigger is whichever is lower, checked at every step of a turn and at the end of it. After a pass the trigger re-arms only once the context has grown a tenth of the trigger past what the pass left. 0 leaves the absolute budget as the only trigger. Daemon-side: no live reload. |
| compaction. | integer | 300000 | Absolute context-token budget for automatic compaction: the trigger is the smaller of this and compaction.auto_compact_threshold × the effective input budget (window − output reservation − safety buffer), checked at every step of a turn and at the end of it (on by default at 300K so a 1M-window model's distant 85% isn't the only trigger). 0 disables (the percentage alone). A session's /autocompact sets its own on top (live, and kept across a restart) until /autocompact reset returns it to this one. Daemon-side: no live reload. |
| compaction. | integer | 3 | How many times in a row a plugin or hook veto at core.compaction.gate may put a due automatic compaction pass off. Once that many consecutive checks have been put off, the next due pass runs whatever the hooks say; any pass that runs (automatic, /compact, or overflow recovery) starts the count over. 0 = a veto never puts a pass off. Overflow recovery is never gated, so a plugin can delay reclaim but never block it. /context shows the passes put off so far. Daemon-side: no live reload. |
| compaction. | float | 0.25 | The largest share of the automatic-compaction trigger (of the effective input budget when automatic compaction is off) any single tool result may occupy. A tool result larger than this (e.g. a big web fetch or a whole-file read) is **spilled to a file under /tmp** before compaction measures the context: the full result is written to a file and the in-context content becomes a short [Tool result spilled to a file] pointer naming the path, so the agent can read it back with fs_read (offset/limit) or grep if it needs the detail. Nothing is destroyed. This is the only reclaim that reaches a result inside the preserved recent turn(s), which Summary leaves untouched. 0 disables the spill. |
| compaction. | float | 0.25 | The largest share of the automatic-compaction trigger the kept recent turns may occupy. When the last preserve_recent_turns turns are larger than that (the usual case for an automatic pass, which meets one very long turn) the cut moves forward inside them to the earliest step (a user or assistant message, never between a tool call and its result) whose tail fits; the last step is always kept. Before this cap, keeping a 400K-token turn whole reclaimed almost nothing. 0 disables the cap (turns only). Daemon-side: no live reload. |
| compaction. | integer | 1 | How many of the most recent user turns a compaction keeps verbatim (a user turn runs from one of your messages to before the next; kcode's own injections and an earlier summary do not count as turns). Everything before them is summarised. Daemon-side: no live reload. |
| compaction. | integer | 5 | Post-compaction file restore: after a Summary compaction, re-read this many of the session's most-recently-read files verbatim into the buffer (source: the fs tools' read-state ledger), so the agent doesn't have to rediscover the files it was working in. Files whose reads survived compaction (path still present in the preserved tail) are skipped; each file is capped at 5k tokens (truncated with a marker). 0 disables the restore. |
| compaction. | integer | 3 | Post-compaction skill restore: after a Summary compaction, re-inject this many of the session's most-recently-invoked skills' current instructions into the buffer (source: the skills the session ran, by the agent or by you, a script skill once its code returned a result, any other once its instructions reached the model, re-resolved against the live skill registry, a skill edited mid-session restores current, a deleted one drops out). A skill whose invocation survived compaction (its name still in the preserved tail) is skipped; each skill is capped at 5k tokens (head-truncated with a marker). 0 disables the restore. The skill catalog needs no restore: it lives in the run_skill tool's descriptor, outside the compacted history. |
| compaction. | integer | 25000 | Total token budget for one post-compaction skill-restore pass (byte-estimated at ~4 bytes/token; Claude Code's 25k budget is the precedent). The restore walks the invoked-skill recency list until it has compaction.restore_skills skills or this budget is spent, whichever comes first. 0 disables the restore. |
| compaction. | integer | 50000 | Total token budget for one post-compaction file-restore pass (byte-estimated at ~4 bytes/token). The restore walks the recency list until it has compaction.restore_files files or this budget is spent, whichever comes first. 0 disables the restore. |
| compaction. | integer | 20000 | Output-token ceiling for one compaction summarization run. Far past useful: the cap bounds a provider retry loop or a model that ignored the summary template so a runaway summary can't burn the model's whole output budget. Applies to the next built compaction engine (per-session boot or /compact). |
| event_bus | |||
| event_bus. | integer | 256 | Documented only by its default. Run kcode config defaults for the full table. |
| eventsource_fs | |||
| eventsource_fs. | boolean | true | Master switch for the session's project file watcher. On (the default) the watcher feeds core.fs.change trigger events and the batched <cp:fs-change> stream, both gitignore-filtered. Set false and no watch is registered at all: file triggers and <cp:fs-change> go silent for every session, and the session stack stops paying the watch cost (the default backend is an FSEvents stream per watcher, with a polling snapshot-diff fallback (file_watcher.backend, default "fsevents"; the poller's file_watcher.poll_interval_ms defaults to 500ms) so the saving is one background stream, or one poll thread and its periodic directory scans when the fallback is in force). Restart-only (a deep lib [section] knob). |
| eventsource_fs. | integer | 5 | How long (seconds) a recorded agent self-write suppresses the matching path from the external <cp:fs-change> stream: the window that keeps the agent's own Write/Edit churn out of its file-change notices. The session's project file watcher also feeds core.fs.change trigger events (gitignore-filtered, .git/ always excluded) that plugin kcode.on_event("core.fs.change", …) handlers hook. Restart-only (daemon-read). |
| eventsource_timer | |||
| eventsource_timer. | array | [] | Cron expressions (six-field: sec min hour dom mon dow) registered as session timer triggers, read in local time: the Mac's time zone, followed when it changes. Across a daylight-saving change, a time the clock skips fires once at the jump and a time it reads twice fires once; a schedule that runs every hour fires in each hour the clock shows. Each fire publishes a core.timer.tick trigger event from its own source, timer:<expression>, so the rate limits count each cron apart and two due at the same moment both fire: hookable by a plugin's kcode.on_event("core.timer.tick", …) handler and rendered on the /control drawer as <cp:event-trigger>. Empty (the default) means no timer source or scheduler task runs for the session. An invalid expression logs a warning and is skipped. Restart-only (daemon-read). |
| eventsource_timer. | integer | 0 | Delays each fire of an eventsource_timer.crons timer and of a project [[hooks]] timer by a random time from zero up to this many milliseconds, so timers set for the same moment don't all run at once. 0 (the default) fires on time. Plugin schedules (manifest [triggers], kcode.on_cron) are never delayed. Restart-only. |
| file_watcher | |||
| file_watcher. | string | "fsevents" | Documented only by its default. Run kcode config defaults for the full table. |
| file_watcher. | integer | 200 | Documented only by its default. Run kcode config defaults for the full table. |
| file_watcher. | integer | 256 | Documented only by its default. Run kcode config defaults for the full table. |
| file_watcher. | integer | 500 | Documented only by its default. Run kcode config defaults for the full table. |
| headless | |||
| headless. | integer | 50 | Turn cap for the headless one-shot arm (kcode -p): the run stops after this many provider turns even if the model is still calling tools. Reads the layered [headless] section (env form KCODE_HEADLESS__MAX_TURN_COUNT); listed by kcode config defaults. |
| headless. | integer | 2048 | Delta-batch flush threshold for kcode -p --output-format ndjson: streamed text/thinking chunks accumulate and emit as one JSON line when the buffer holds a newline or reaches this many bytes, whichever comes first, set 1 for per-chunk lines (lowest latency, most lines). The ndjson schema (one versioned JSON object per turn event, final envelope last) lives in libs/headless/spec.md. Env form KCODE_HEADLESS__NDJSON_FLUSH_BYTES. |
| health | |||
| health. | integer | 3000 | Local health collection time budget in milliseconds. Completed findings are retained when the budget expires, with an incomplete-report warning. No network probes or repairs. Restart-only. |
| health. | integer | 2 | Maximum concurrent local health collectors. Limits diagnostic work while reports remain advisory and non-blocking. Restart-only. |
| health. | boolean | true | Run advisory local checks once per app launch and when each session opens. Global findings appear outside sessions; project findings stay inside their session. Disable to skip automatic checks; /doctor and Recheck still work. Restart-only. |
| http_client | |||
| http_client. | integer | 30 | Documented only by its default. Run kcode config defaults for the full table. |
| kvstore | |||
| kvstore. | integer | 5 | How long a connection waits on a locked database before it fails (PRAGMA busy_timeout). The daemon opens the user store once and shares that pool across sessions, so this rarely trips. Restart-only. |
| kvstore. | string | "wal" | sqlite journal mode for both stores: wal (readers never block the writer; the default), delete, or truncate. Restart-only. |
| kvstore. | integer | 268435456 | Memory-map budget per connection (PRAGMA mmap_size, 256 MiB by default): reads of a mapped page skip the read syscall and sqlite's page cache copy. 0 turns mapping off. Applied on every connection. Restart-only. |
| kvstore. | path? | unset | Pins the project-scope store to <path>/.kcode/storage.db instead of the project root kcode resolved. Restart-only. |
| kvstore. | string | "normal" | How hard sqlite syncs a commit to disk (PRAGMA synchronous): off, normal, full, or extra. Under the default WAL journal, normal syncs the log only at a checkpoint, so a per-turn transcript save costs no fsync of its own; a commit is still durable across an app crash, and only a power loss or OS crash can roll back the newest commits. full (sqlite's own default) fsyncs the WAL on every commit: pick it when that last-commit window matters more than write latency. Restart-only. |
| kvstore. | path? | unset ( | Where the user-scope sqlite store lives. Every project shares this one file for user-scope rows (memories, prompt history, the cost ledger, workspace state). Restart-only. |
| logger | |||
| logger. | string | "json" | Log line format: json (machine-greppable, one object per line) or pretty (human-readable multi-line). Restart-only. |
| logger. | string | "info" | Minimum level written to the log file: trace | debug | info | warn | error. A non-empty RUST_LOG environment variable overrides this entirely (standard tracing EnvFilter syntax). Restart-only. |
| logger. | string? | ~/.kcode/log | Directory for kcode's diagnostic log files, daily-rolling kcode.log.YYYY-MM-DD (JSON lines by default, for machines) plus two human-read side logs written as one tab-separated row per event: transport.log.YYYY-MM-DD with every outbound HTTP request’s outcome, method, URL (query stripped), status, TTFB, and on failure the full error cause chain, the first stop when a provider turn fails; and agentloop.log.YYYY-MM-DD with the agent loop's branch decisions (turn/round start, continuation rulings, the compaction gate, doom bails, retries, overflow recovery) and the numbers behind each. Tail them with make logs / make logs-transport / make logs-agent. Logs never write to the terminal: the TUI owns the screen and headless stdout/stderr are wire formats. A leading ~/ expands to your home directory. Restart-only. |
| logger. | integer | 10 | How many daily log files to keep per stream: the app log (kcode.log.*), the transport log and the agent-loop log each keep this many, today's included; older ones are deleted at startup. 0 keeps everything. Restart-only. |
| lsp_client | |||
| lsp_client. | integer | 2500 | Total wait cap for a fresh diagnostics publish after a sync, and for the check the sync's save starts (rust-analyzer's cargo check), for both the post-edit digest and the lsp tool's diagnostics. On timeout, or when the turn is stopped, the edit's result simply carries no digest (fail-soft, never an error); a diagnostics query reports what it has, marked timed_out, and checking while the check still runs. Restart-only. |
| lsp_client. | integer | 300 | How soon after a save a language server's work must begin to count as the check that save started, such as rust-analyzer's cargo check. A diagnostics wait waits for that check to finish, so it doesn't report the errors from before the edit; on a server not yet seen to run a check after a save, it waits this long for one to begin. Restart-only. |
| lsp_client. | integer | 150 | Quiet window after the first fresh publishDiagnostics following an edit, so a multi-part publish settles before the digest reads it. Restart-only. |
| lsp_client. | boolean | true | Post-edit diagnostics digest: after fs_edit/fs_write, sync the file to its language server and append fresh errors to the tool result + a <cp:lsp-diagnostics> emission. Only already-spawned servers are probed: an edit never boots one; a language without a running server is silently skipped. Restart-only. |
| lsp_client. | integer | 20 | Max error rows the post-edit digest appends per edited file. Restart-only. |
| lsp_client. | integer | 300 | How long a project's count of source files per language is kept before it is taken again. The count picks which server a path-less workspace_symbol queries and which servers a new session pre-warms; sessions in one project share it, so neither walks the project on every call. 0 counts every time. Restart-only. |
| lsp_client. | integer | 3 | Maximum directory depth the lsp tool's lsp_outline operation walks when building a workspace-wide symbol outline. Restart-only. |
| lsp_client. | array | [ "target/", "node_modules/", "vendor/" ] | Relative-path substrings that exclude files from the lsp_outline walk. Restart-only. |
| lsp_client. | integer | 2 | How many of a project's top languages (ranked by source-file count, computed via a gitignore-respecting walk so target//node_modules/ don't skew it) get their language server pre-warmed (spawned + indexing in the background) the moment a session starts. The agent's first lsp navigation call then hits a warm or warming server instead of paying rust-analyzer's full cold start mid-turn. Only languages with a configured server are eligible; a missing binary is logged and skipped, never fails the session. 0 disables pre-warming (fully lazy: servers then spawn on first use). Restart-only. |
| lsp_client. | integer | 60 | How long to wait for an LSP server's initialize handshake (and each subsequent request) before declaring it bad. Restart-only. |
| lsp_client. | map? | { rust = "rust-analyzer", typescript/javascript = "typescript-language-server --stdio", go = "gopls", python = "pyright-langserver --stdio", c/cpp = "clangd", bash = "bash-language-server start" } | Per-language LSP server-command map driving the agent's lsp tool and the post-edit diagnostics digest: language id (rust, python, typescript, go, …) to the command that spawns its server (single string, whitespace-split, e.g. typescript-language-server --stdio). Defaults cover Rust, TypeScript/JavaScript, Go, Python, C/C++, and Bash; a missing binary only matters when that language is actually used (servers spawn lazily). In the daemon the pool is shared per project: one language server per language serves every session rooted there, and it shuts down when the project's last session stops or is deleted. Restart-only. |
| lsp_client. | string | "bash-language-server start" | Documented only by its default. Run kcode config defaults for the full table. |
| lsp_client. | string | "clangd" | Documented only by its default. Run kcode config defaults for the full table. |
| lsp_client. | string | "clangd" | Documented only by its default. Run kcode config defaults for the full table. |
| lsp_client. | string | "gopls" | Documented only by its default. Run kcode config defaults for the full table. |
| lsp_client. | string | "typescript-language-server --stdio" | Documented only by its default. Run kcode config defaults for the full table. |
| lsp_client. | string | "pyright-langserver --stdio" | Documented only by its default. Run kcode config defaults for the full table. |
| lsp_client. | string | "rust-analyzer" | Documented only by its default. Run kcode config defaults for the full table. |
| lsp_client. | string | "typescript-language-server --stdio" | Documented only by its default. Run kcode config defaults for the full table. |
| mcp_protocol | |||
| mcp_protocol. | integer | 256 | In-flight requests allowed per MCP server; a further call fails fast with json_rpc.client.too_many_pending instead of queueing. The same figure bounds the buffer of responses that arrive before their call registered. Env form KCODE_MCP_PROTOCOL__MAX_CONCURRENT_PENDING. |
| mcp_protocol. | integer | 8 | How long kcode mcp list may spend probing one server (connect → initialize → count tools) before that row reads probe timed out, so a slow npx cold start or a dead remote never hangs the listing. The probe connects on the rest of this section too. Env form KCODE_MCP_PROTOCOL__PROBE_TIMEOUT_SECS. |
| mcp_protocol. | integer | 30 | How long one request to an MCP server may wait for its response before the call fails with a timeout. Applied to every server the MCP plugin runtime connects to, on first connect and on every supervisor reconnect. Over HTTP it bounds each POST, the event stream that answers it and any resume of that stream included. Time the user spends on a question the server asked doesn't count. Env form KCODE_MCP_PROTOCOL__REQUEST_TIMEOUT_SECS. |
| mcp_protocol. | integer | 15 | How long an SSE-transport connect waits for the server's endpoint event (the MCP SSE handshake naming the per-session message URL) before the connect fails with mcp_protocol.sse.endpoint_timeout. Env form KCODE_MCP_PROTOCOL__SSE_ENDPOINT_TIMEOUT_SECS. |
| memory_consolidator | |||
| memory_consolidator. | boolean | true | GPU/daemon build only: turn the automatic background memory consolidator on. On by default: the daemon distils recent session transcripts into new memories at a turn boundary once both cadence gates pass. Toggle it live with /memory consolidate on|off (which persists this key AND relays a live SetConsolidatorEnabled, so it applies without a restart); a manual /memory consolidate or the agent's run_command consolidate always runs regardless. A hand-edit of this key applies on restart (the daemon reads it once at boot). |
| memory_consolidator. | integer | 200000 | Documented only by its default. Run kcode config defaults for the full table. |
| memory_consolidator. | integer | 3 | GPU/daemon build only: cap on how many memories one consolidation run may create or update, bounds cost + churn. Restart-only (daemon-read). |
| memory_consolidator. | integer | 10 | GPU/daemon build only: how many recent sessions (sharing the triggering session's project) feed one run's transcript corpus, bounds input size + cost. Restart-only (daemon-read). |
| memory_consolidator. | integer | 24 | GPU/daemon build only: minimum whole hours since the last run before an automatic consolidation may fire. One of the two cadence gates (both must pass); a manual run ignores it. Restart-only (daemon-read). |
| memory_consolidator. | integer | 5 | GPU/daemon build only: minimum new sessions observed since the last run before an automatic consolidation may fire (derived from the session list, so it survives restarts). The other cadence gate; a manual run ignores it. Restart-only (daemon-read). |
| memory_consolidator. | float | 0.8 | GPU/daemon build only: a distilled candidate the consolidator tags user (global) scope is only written to the user store when its confidence is at least this; a lower-confidence cross-project guess is downgraded to project scope, keeping the global store clean. Restart-only (daemon-read). |
| memory | |||
| memory. | boolean | false | Per-turn memory auto-recall: when on, each turn's input queries the memory store's ranking (relevance × confidence × recency) and the top-k hits at or above the confidence floor inject as a <cp:memory-recall> block beside your message, visible in /control and as a one-line 'Recalled N memories into context: …' notice in the chat. Auto-recalls never stamp a memory's recency (last_used_at) and raise no <cp:memory> operation events: only explicit recalls count as use. Off by default. Toggle it live from Settings › Memory › "Memory auto-recall": the toggle persists this key AND relays it through the daemon's generic ApplySettings settings relay, so running sessions honour the change at their next turn, no restart. A hand-edit of this key still applies on the next daemon boot only. |
| memory. | float | 0.8 | Only memories at or above this confidence (0.0–1.0) inject on auto-recall, the best matches among them however many below it match better; user-saved memories default to 1.0, consolidator-distilled ones carry their distillation confidence. Default 0.8 (raised from 0.5): only high-confidence memories inject uninvited. Live-appliable through the daemon's ApplySettings settings relay (no UI row yet); a hand-edit applies on the next daemon boot. |
| memory. | integer | 3 | How many memories one auto-recall injects at most. Live-appliable through the daemon's ApplySettings settings relay (no UI row yet); a hand-edit applies on the next daemon boot. |
| model_discovery | |||
| model_discovery. | integer | 4 | How many of those Ollama /api/show requests run at once; 0 counts as 1. Restart-only. |
| model_discovery. | integer | 64 | The most models kcode asks Ollama about one by one (/api/show) for the context window and the abilities (tools, images, thinking) its model list leaves out; the rest are listed without them. Restart-only. |
| model_discovery. | integer | 8388608 | The largest reply kcode reads from a provider's server when it requests the model list, in bytes (8 MiB); a longer one is refused. Restart-only. |
| model_discovery. | integer | 10000 | How long one request to a provider you added may take when kcode reads which models its server serves, in milliseconds. A server that takes longer is reported as not answering, and its last list stays. Restart-only. |
| models_dev | |||
| models_dev. | boolean | true | Whether kcode downloads the model catalog from models.dev (https://models.dev/api.json, about 5 MB): the list of providers, models, prices and context windows the /model picker and the cost figures read. On, the app checks for a newer copy at launch when the saved one is older than 4 hours, and again whenever it goes that stale while the app is open: a failed check is tried again after five minutes. A check sends the saved copy's version, so the 5 MB downloads only when the catalog changed. Off, nothing is downloaded: kcode uses the last copy it saved, else the catalog compiled into this build, so models published after the build don't appear. Restart-only. |
| notification_log | |||
| notification_log. | integer | 500 | GPU/daemon build only: how many entries the durable notification center keeps in its one global, cross-project log (the ~/.kcode user scope); the oldest drop past this. The center records session state transitions and replays on attach: distinct from the transient per-session command-reply notices and the live tile-attention glow. Restart-only. |
| notification_log. | boolean | false | GPU/daemon build only: raise a notification-center entry when a working session finishes (returns to idle). Off by default: a notification on every completed turn buries the ones that need you. Toggle it live from the Settings page's General → 'Notify: turn complete' row: the toggle persists here and relays a live SetNotificationTriggers to the daemon, so it applies without a restart. A hand-edit of this key applies on restart. |
| notification_log. | boolean | true | GPU/daemon build only: raise a notification-center entry when a session hits an error. One of the three center triggers (needs-input + error notify by default; completion is opt-in). Toggle it live from the Settings page's General → 'Notify: errors' row: the toggle persists here and relays a live SetNotificationTriggers to the daemon, so it applies without a restart. A hand-edit of this key applies on restart. |
| notification_log. | boolean | true | GPU/daemon build only: raise a notification-center entry when a session starts needing your input. One of the three center triggers (needs-input + error notify by default; completion is opt-in). Toggle it live from the Settings page's General → 'Notify: needs input' row: the toggle persists here and relays a live SetNotificationTriggers to the daemon, so it applies without a restart. A hand-edit of this key applies on restart. |
| notifications | |||
| notifications. | boolean | true | Play the OS alert sound with an escalated OS notification: an unfocused-window escalation, a permission request, a needs-input, an error, an agent, plugin, skill or hook message, or a turn finishing, posts the banner and sounds with it. On by default; the sound rides the OS notification, so the OS's own notification-sound settings still govern it. Read once at GPU client startup (restart-only). |
| permissions | |||
| permissions. | string | "auto" | The permission mode a new session starts in, spelled as /permissions spells it. Unset, it is auto: tool calls run without a permission prompt, except calls that read or write a secret location (permissions.secret_paths), and deny rules still apply. Set "accept-edits" for a prompt before a shell command that changes things and a write outside the project, or "default" for a prompt before each edit too. Headless kcode -p starts in it too. accept_edits works as well. A session keeps a mode it is given later (through /permissions or the launch flags) when it is resumed. A mode one session is given never changes this setting. /permissions reset returns a session to it. In Settings its row steps through the four modes rather than taking typed text. Restart-only. Env form KCODE_PERMISSIONS__DEFAULT_MODE. |
| permissions. | integer | 500 | How long an interactive permission prompt waits for the shell planner's evidence (resolved binary, parsed argv, side-effect class, glob match counts) before showing the plain command-string prompt instead. The evidence card applies to bash prompts only; expiry or a planner failure degrades the card, never the decision: the prompt still appears, just without the evidence lines. Env form KCODE_PERMISSIONS__PLAN_EVIDENCE_TIMEOUT_MS. |
| permissions. | array | [ "~/.ssh", "~/.gnupg", "~/.aws", "~/.azure", "~/.config/gcloud", "~/.kube", "~/.docker/config.json", "~/.netrc", "~/.git-credentials", "~/.config/git/credentials", "~/.config/gh", "~/.config/github-copilot", "~/.npmrc", "~/.yarnrc.yml", "~/.pypirc", "~/.gem/credentials", "~/.cargo/credentials", "~/.cargo/credentials.toml", "~/.password-store", "~/.config/op", "~/.vault-token", "~/.terraform.d/credentials.tfrc.json", "~/.codex/auth.json", "~/.claude/.credentials.json", "~/.local/share/keyrings", "~/Library/Keychains", "/Library/Keychains", "~/Library/Cookies", "~/Library/Safari", "~/Library/Application Support/Google/Chrome", "~/Library/Application Support/Chromium", "~/Library/Application Support/BraveSoftware", "~/Library/Application Support/Microsoft Edge", "~/Library/Application Support/Arc", "~/Library/Application Support/Firefox", "~/.mozilla", "~/.config/google-chrome", "~/.config/chromium", "~/.config/BraveSoftware", "~/.bash_history", "~/.zsh_history", "~/.zhistory", "~/.local/share/fish/fish_history", "~/.python_history", "~/.node_repl_history", "~/.psql_history", "~/.mysql_history", "~/.zshrc", "~/.zshenv", "~/.zprofile", "~/.bashrc", "~/.bash_profile", "~/.profile", "~/.config/fish/config.fish" ] | The places where a read outside the project needs permission (it replaces permissions.deny_external_paths_default, which made every read outside the project need permission). An fs_read, a grep, or a shell command that only reads (cat /etc/hosts, grep -rn TODO ~/code/other) runs without a prompt wherever it reaches, unless it reads a file in one of these places or searches a folder above one: grep -rn token ~ needs permission, because the search would read ~/.ssh. Listing names needs no permission (fs_glob, ls ~/.ssh). A tool that declares itself read-only (an MCP tool its server marks read-only, a plugin's Lua tool, view_image, lsp) needs permission the same way when its path arguments name one of these places or a folder above one: a string in them counts as a path, a file: URL as the path it names, ~/… in the home folder and a relative path from the project, with its symlinks followed. kcode's own tools say which arguments name files (view_image's and lsp's path) so an argument that names none, such as a search query or a question, never needs permission however it starts; every argument of an MCP tool counts, and of a plugin tool that doesn't list its own (path_arguments). A write outside the project still needs permission. An entry starts with ~/ (the home folder) or /; its names may hold the globs *, ? and […], each matching within one name, and names are compared without regard to case. An fs_read or grep path counts where its symlinks lead; a shell command's words count as written. A shell script given as text (sh -c '…', eval '…') counts as the commands it runs, and code given to an interpreter (node -e '…', python3 -c '…') counts when it writes out one of these places, as open("~/.ssh/id_rsa") does; a path the code builds some other way isn't seen. kcode's own credential file (auth.toml in the data dir) is always on the list. An allow rule, such as one /add-dir adds, still lets a read there run. In auto mode these are the only places where a call needs permission. An empty list lets every read run. The default list covers credentials and keys (~/.ssh, ~/.gnupg, ~/.aws, ~/.kube, ~/.netrc, ~/.config/gh, ~/.npmrc, ~/.cargo/credentials, …), the macOS keychains, browser profiles, shell and tool history, and the shell startup files, which often export tokens; kcode config defaults prints it whole. Restart-only. |
| plugin_drafts | |||
| plugin_drafts. | integer | 1048576 | The most bytes one plugin draft's files may take in all (1 MiB); a larger draft is refused naming this setting. Restart-only. |
| plugin_drafts. | integer | 16 | The most plugin drafts that may wait for review in Settings › Plugins at once; past it kcode.plugins.stage is refused until you install or discard one. Restart-only. |
| plugin_drafts. | integer | 64 | The most files one plugin draft written with kcode.plugins.stage may hold; a larger draft is refused naming this setting. Restart-only. |
| plugin_grants | |||
| plugin_grants. | table ( | none | Hosts off the public internet that you let a plugin fetch from, beyond the ones its manifest names: [plugin_grants.<name>] net_http = ["nas.local", "192.168.1.20"]. Each host is read as a "net.http" list reads it: *.corp.lan covers corp.lan and every host under it. A grant counts only while the plugin's [capabilities] asks for "net.http"; Settings › Plugins and kcode plugins list say so when one doesn't. kcode reads the table only from your own config.toml, never from a project's file, the health report and kcode doctor warn about a project file that sets it (config.user-only), so only you can widen what a plugin reaches, and the install review never asks for it. A script skill gets no grant. A host is checked against the grant at each fetch, so an edit in config.toml reaches open sessions as soon as the open window notices the save. Removing the plugin, in Settings or with kcode plugins remove, removes its grant. Settings › Plugins and kcode plugins list show it as hosts your config.toml allows: …; a key kcode doesn't read, a value that isn't a list of strings, and a name no plugin can have are named in the health report and by kcode doctor. |
| plugin_host | |||
| plugin_host. | integer | 4194304 | The most bytes of each of its two output streams a plugin's kcode.exec program returns (4 MiB); the rest is read and dropped, and the result's truncated is true. Restart-only. |
| plugin_host. | integer | 67108864 | The largest response body a plugin kcode.fetch returns, in bytes (64 MiB); a larger one fails, naming this setting. Script skills' fetches use it too. Restart-only. |
| plugin_host. | integer | 600 | How many fetches one plugin may start in a minute; one past it fails, naming this setting. Restart-only. |
| plugin_host. | integer | 120 | How long one plugin kcode.fetch may take, its redirects and its body included, in seconds; a fetch that runs past it fails. Script skills' fetches use it too. Restart-only. |
| plugin_host. | integer | 50000 | How many entries a plugin's kcode.fs_list returns at most; the listing stops there. Script skills' listings use it too. Restart-only. |
| plugin_host. | integer | 67108864 | The largest file a plugin's kcode.fs_read returns, in bytes (64 MiB); a larger one fails, naming this setting. Script skills' reads use it too. Restart-only. |
| plugin_host. | integer | 536870912 | The most bytes one plugin kcode.fs_write may put in a file (512 MiB); a larger write fails, naming this setting, and leaves the file as it was. Script skills' writes use it too. Restart-only. |
| plugin_host. | integer | 100 | The most sessions one kcode.sessions.list returns; a call's limit asks for fewer, and the page's next reads on. Restart-only. |
| plugin_host. | integer | 1048576 | The most bytes of text and tool arguments one kcode.sessions.read returns (1 MiB); the page ends before the record that would pass it, though a page always holds at least one record. Restart-only. |
| plugin_host. | integer | 500 | The most records one kcode.sessions.read returns; a call's limit asks for fewer. A page that stops here says there is more, and its next reads on. Restart-only. |
| plugin_host. | integer | 65536 | The most bytes of one record's text, or of a tool call's arguments, that kcode.sessions.read returns (64 KiB); the rest is cut and the record's truncated is true. Restart-only. |
| plugin_host. | boolean | true | Re-read a plugin when a file under one of its directories changes, so an edited plugin takes effect in the running session instead of only in the next one. On (the default) each session arms one watcher covering whichever of the built-in, user (~/.kcode/plugins/) and project (<project>/.kcode/plugins/) roots exist. Set false and no watch is registered: the session keeps the plugin set it loaded at start, and skips the watch cost (an FSEvents stream by default: file_watcher.backend; the polling snapshot-diff fallback's file_watcher.poll_interval_ms defaults to 500ms). Restart-only (a deep lib [section] knob). |
| plugin_host. | integer | 5 | How many subagents one plugin may start with kcode.spawn_subagent in plugin_host.spawn_subagent.window_secs; one past it fails with a catchable error naming both. Restart-only. |
| plugin_host. | integer | 600 | The length of the window plugin_host.spawn_subagent.max_per_window counts a plugin's subagent starts in, in seconds. Restart-only. |
| plugin_links | |||
| plugin_links. | string | none | A linked plugin: <name> = "/abs/dir" under the top-level [plugin_links] table loads the plugin from that folder, anywhere on the filesystem, outside the managed plugin dirs. Written by Settings › Plugins › "+ Add plugin from folder…" (the daemon validates the folder's plugin.toml first) and cleared by Remove; hand-editing works too. A link whose path stops existing rows as missing in Settings › Plugins with a loud notice, never a silent skip. Its own namespace, never inside [plugins.<name>], whose keys are the plugin's settings. A linked plugin adds its commands, skills, agents, output styles and themes like an installed one. User scope; a link added or removed in Settings, or by hand in config.toml, applies to open sessions at once. |
| plugin_marketplace | |||
| plugin_marketplace. | integer | 86400 | Controls how long a marketplace index is cached. There is currently no public kcode marketplace; use kcode plugins install <folder> for local plugins. Read by each kcode plugins command. |
| plugin_marketplace. | integer | 268435456 | Limits the decompressed size of a marketplace plugin archive. There is currently no public kcode marketplace; use kcode plugins install <folder> for local plugins. Read by each kcode plugins command. |
| plugin_runtime_lua | |||
| plugin_runtime_lua. | integer | 5 | The longest, in seconds, one Lua plugin's intercept may run. The intercept chain sits on every tool call and turn, so this is tighter than plugin_runtime_lua.max_execution_seconds: a plugin still running then is stopped and passed over, and the chain goes on. The time counts even while a prompt its kcode.run_tool raised is open: the chain goes on without it. Restart-only. |
| plugin_runtime_lua. | integer | 30 | The longest, in seconds, a Lua plugin's main.lua or one of its tool calls, watched events, schedule fires, provide calls or slash commands may run; code still running then is stopped, and the call fails naming this setting. Time the plugin waits for the user on a question or permission prompt doesn't count. Restart-only. |
| plugin_runtime_lua. | integer | 10 | The most questions one Lua plugin may have waiting for your answer, asked with kcode.ask_user(spec, fn); past it kcode.ask_user raises an error naming this setting. Restart-only. |
| plugin_runtime_lua. | integer | 1000 | The most kcode.after timers one Lua plugin may have waiting at once; past it kcode.after raises an error naming this setting. Restart-only. |
| plugin_runtime_lua. | integer | 67108864 | Documented only by its default. Run kcode config defaults for the full table. |
| plugins | |||
| plugins. | per-plugin schema | none | Per-plugin settings: a plugin declares its schema as [settings.<key>] tables in its plugin.toml (type string|integer|number|boolean|enum|secret + default + description); users override values here (project config layers over user config). The plugin reads the resolved value via kcode.settings.get(key). A value of the wrong type, or a choice that isn't one of an enum's options, gives the plugin its declared default, and a key the plugin doesn't declare never reaches it; each is named in /plugins, under the setting in Settings › Plugins, in the health report and by kcode doctor, and the plugin's other settings still apply. Read when a session starts, so an edit (in Settings, or by hand in config.toml, which the open window notices on save) reaches the next new session. Every key under [plugins.<name>] belongs to the plugin's own settings vocabulary: the management keys live in their own top-level namespaces ([plugin_links] and disabled_plugins), so a plugin setting named path or enabled (kcode-tail declares path) works normally. A secret setting, such as an API token, is never kept here: it takes no default, you set it in Settings › Plugins, and kcode keeps it in ~/.kcode/auth.toml (a project plugin's under its folder, any other plugin's under its name), showing only whether one is saved. One written under [plugins.<name>] changes nothing and is named like a wrong value. Removing the plugin removes its secrets. |
| procs | |||
| procs. | integer | 2000 | The /procs snapshot poll cadence in milliseconds: how often the daemon re-scans the process table and pushes ProcsSnapshots while a client watches. Default 2000. The scan runs only while someone watches; closing the overlay cancels it to zero work. |
| procs. | boolean | false | Show every process in /procs, not only the dev-relevant ones: the processes no watch rule matches appear as other rows after the classified ones (pid, working directory and any LISTEN ports included) which is how to read the name or command line a new [[procs.watch]] rule should match. An unmatched process stays other even when it listens, so the header's build/server/database/watcher counts stay the dev-relevant ones. Default false. Restart-only: the daemon reads it at boot. |
| procs. | array | [] | The user watch rules layered ahead of the built-in /procs classifier table, as an array of tables [[procs.watch]] with match (case-insensitive: a substring of the exe name, or whole words of the command line, each word reduced to its last path component, so vite matches node_modules/.bin/vite, and go build must appear as two consecutive words; never a substring of a longer word, so --capture-python is not python), kind (build | server | database | watcher; runner is an alias for watcher), and an optional label. First-match-wins, so a user rule overrides a built-in matching the same text; rules with an unknown kind or empty match are dropped. cargo runs a subcommand it does not ship as a process of its own named cargo-<name> (a cargo watch run is the process cargo-watch), so a rule for one should match cargo-<name>. |
| project_hook_runtime | |||
| project_hook_runtime. | integer | 10 | How long a project hook's webhook POST may take before it fails, in seconds. A POST past it is named in a hook notice like any other failed POST. Restart-only (the daemon reads it once at boot). |
| providers | |||
| providers. | "openai" | "anthropic" | "openai" | Add a provider of your own, from Settings › Providers › + Add a provider…, or by hand: a [providers.<id>] table whose id kcode doesn't list adds a server that speaks the OpenAI API (Chat Completions) or the Anthropic API (Messages) at base_url, a hosted vendor kcode doesn't list, a server on your network, or Ollama, LM Studio, llama.cpp or vLLM on this Mac. The id is 1 to 64 lowercase letters, digits, - and _ (never : or .), and names the provider in a model reference: lab:qwen3:0.6b is the model qwen3:0.6b on the provider lab.
`toml
[providers.lab]
base_url = "http://localhost:11434/v1"
api = "openai"
name = "Ollama"
kcode reads which models the server serves (<base_url>/models, or <base_url>/v1/models for the Anthropic API), and reads each model's context window where the server says it (LM Studio, Ollama, llama.cpp); the models appear in the /model picker and Settings › Providers beside every other provider's, and run like them. The last list is kept in provider-models.json in the data folder, so the models stay listed while the server is off. A provider needs no key: when its server needs one, save it with kcode auth login <id>. A model on this Mac or your network — a loopback address, a private address, a one-word host name or one ending .local, .lan, .home.arpa or .internal — costs nothing in /cost and /stats. Saving config.toml adds, changes or removes the provider at once, with no restart; a table kcode can't take is named in the log and the others are served. An id kcode already lists can't be added: such a table only moves that provider's base_url`. |
| providers. | string? | the id | The name a provider you added shows as in the /model picker and Settings › Providers. Ignored for a provider kcode lists. |
| providers. | string? | none | Where a provider's requests go. For a provider kcode lists, it moves the endpoint (a proxy or a self-hosted deployment) and the provider is served at the new address as soon as the file is saved; take the line out and it goes back to the vendor's own. For a provider you add (see providers.<id>.api) it is required, and is the address of your server: for the OpenAI API the part before /chat/completions, such as http://localhost:11434/v1 for Ollama or http://localhost:1234/v1 for LM Studio; for the Anthropic API the part before /v1/messages, such as http://localhost:11434; a trailing /v1 is taken off. An http or https URL with no query, fragment or user name. A value that doesn't parse as a URL keeps that provider from being served, and the log names it. |
| scheduler | |||
| scheduler. | string | "skip" | What a timer does with the fires it missed while the computer slept: config crons (eventsource_timer.crons), project [[hooks]] timers, plugin schedules and the agent's set_timer cron timers alike. "skip" (the default) fires once, for the newest missed time; { catch_up = N } fires once for each missed time, up to N of the newest, oldest first; "fail_fast" fires once like skip and logs a warning naming how many fires were dropped. A fire whose time comes while kcode is awake is never missed. A [scheduler] section that names a key kcode does not know is not read, and its policy falls back to skip. Restart-only. |
| session_daemon | |||
| session_daemon. | integer | 20 | Cap on agent set_activity reports per session within the activity window: the label-churn guard on the working-strip / tile-marker feed. Sits well above the notify cap (one report per step is fine); over-cap reports are silently dropped with a daemon warn log. Restart-only. |
| session_daemon. | integer | 60 | The agent-activity window length in seconds (pairs with agent_activity_max_per_window). Restart-only. |
| session_daemon. | integer | 3 | Cap on agent-initiated fork_session forks within the fork window: the fork-bomb guard. One budget covers a whole session family: the first session and every fork and worker made from it, so a fork's own forks count against it. An over-cap fork is refused: the agent's call fails with an error naming the cap. User /fork is never capped. Restart-only. |
| session_daemon. | integer | 600 | The agent-fork window length in seconds (pairs with agent_fork_max_per_window). Restart-only. |
| session_daemon. | integer | 10 | Cap on cross-session send_message deliveries per sender session within the mail window, the mail-storm guard: each delivery to an idle recipient drives a wake turn (a real model call), so uncapped mail amplifies like a fork bomb. An over-cap send returns as a tool error the sender model reads. Within-session mail is never capped. Restart-only. |
| session_daemon. | integer | 60 | The agent-mail window length in seconds (pairs with agent_mail_max_per_window). Restart-only. |
| session_daemon. | integer | 5 | Cap on kcode.notify posts per session within the notify window: the spam guard on the notification center. An over-cap notice is not posted: the call answers that it was not, with a reason naming this limit, and the daemon logs a warning (no notification about notifications). Restart-only. |
| session_daemon. | integer | 60 | The agent-notify window length in seconds (pairs with agent_notify_max_per_window). Restart-only. |
| session_daemon. | integer | 3 | Cap on agent-initiated spawn_worktree_session spawns within the worktree window: the worktree-bomb guard. One budget covers a whole session family, as for forks, so a worker's own workers count against it. An over-cap spawn returns as a tool error the agent reads. User /worktree new is never capped. Restart-only. |
| session_daemon. | integer | 600 | The agent-worktree window length in seconds (pairs with agent_worktree_max_per_window). Restart-only. |
| session_daemon. | boolean | true | The always-on session export: the daemon keeps <export dir>/<session-id>.jsonl current for every session, a full overwrite of the stable per-session file at each turn boundary, compaction and session stop (detached and best-effort; a failure warns in the daemon log and never affects the turn; an older export never replaces a newer one), removed when the session is deleted (an export still being written then is dropped) so the export set always mirrors the session store. JSONL schema 2 archives canonical typed history at a fixed watermark, including original replies, reasoning, rich tool results, retained attachment bytes and model-context checkpoints. Compaction does not discard earlier exchanges from this archive. Reads are paged and a failed export leaves the previous file intact. A crash can still lose an uncommitted live tail. Feeds analysis / fine-tuning / memory pipelines outside kcode; /share remains the on-demand two-format export. Set false to turn the feature off. Restart-only (the daemon reads it once at boot). |
| session_daemon. | integer | 1000 | How long, in milliseconds, each window's connection has once the daemon stops to write what is still queued for it: the last thing it hears, such as kcode restarting into a downloaded update. A window reads at once; the bound is for one that stopped reading, which is then closed with the rest left unsent. Restart-only. |
| session_daemon. | integer | 8192 | GPU client mode: the bound on one client connection's outbound message queue. A client that stops reading (a wedged window, a paused debugger) is cut at this many queued messages instead of growing the daemon without bound; its reconnect supervisor dials back in and replays the session snapshot. A bounded queue allocates as it fills, so the large default costs nothing while a client keeps up. Env form KCODE_SESSION_DAEMON__CONN_QUEUE_CAPACITY. Restart-only. GPU/daemon build only. |
| session_daemon. | integer | 512 | GPU client mode: how many control-plane (<cp:*>) rows the daemon keeps per live session and replays to the /control overlay on attach. Older rows evict oldest-first; the lifetime counters survive eviction. 0 keeps none: the overlay then shows the counters but no rows (it kept one). GPU/daemon build only. |
| session_daemon. | integer | 1000 | The /debug window's snapshot cadence: how often (milliseconds) the daemon rebuilds and pushes the full debug snapshot while at least one client is subscribed, no /debug window open anywhere means no tick and zero snapshot work. Restart-only (the daemon reads it once at boot). |
| session_daemon. | string? | ~/.kcode/exports | Where the always-on session exports land (pairs with auto_export). Unset = exports/ under the kcode data dir; a leading ~ expands. Restart-only. |
| session_daemon. | integer | 3 | The /goal driver's no-progress guard: after this many consecutive goal-driven turns that called no tool, the driver disarms with a needs-input notification instead of nudging in circles. 0 disables the guard. Restart-only. |
| session_daemon. | integer | 16777216 | Maximum canonical source bytes in one history delivery. A row larger than this limit produces an explicit read error rather than silently skipping content. Must be positive. Restart-only. |
| session_daemon. | integer | 128 | Maximum display rows in one acknowledged history delivery, for initial replay, paging and live catch-up. Must be positive. This bounds display reads, not the model context or the durable conversation. Restart-only. |
| session_daemon. | integer | 5000 | GPU/daemon build only: how long (milliseconds) the shared background daemon lingers after its last client disconnects before exiting. The daemon is a guaranteed singleton that dies with the app: closing the last kcode window drops the client connection, and once no client remains the daemon shuts down after this grace window (the grace absorbs a client restart/reconnect without tearing down live sessions). Restart-only. |
| session_daemon. | boolean | true | Keep the Mac awake while an agent works (macOS only): the daemon holds a no-idle-sleep power assertion (PreventUserIdleSystemSleep, via the keepawake crate) whenever ≥1 live session is mid-turn, compacting or running subagents (an /agent run, or a child that outlives the turn that started it) **or has watched background commands or a ! shell command outstanding** (any backgrounded bash command is exit-watched by default, and shell_spawn with notify_on_exit: true: an idle session with a build in flight is exactly the walk-away case), and releases it the moment every session is idle with nothing watched. Long agent runs and background builds survive the machine's idle-sleep timer, on AC and battery, while an idle kcode never pins the machine awake. The display may still sleep; lid-closed clamshell sleep is unaffected; the assertion is process-scoped so a daemon crash releases it. Inspect live with pmset -g assertions, where it reads 'kcode is working'. Restart-only (the daemon reads it once at boot). |
| session_daemon. | integer | 5 | Cap on kcode.sessions.open calls per plugin within the plugin-open window, counted by the plugin's name across every session it runs in. An open past the cap is refused: the call raises an error naming this limit. A refused open counts too. Restart-only. |
| session_daemon. | integer | 600 | The plugin-open window length in seconds (pairs with plugin_open_max_per_window). Restart-only. |
| session_daemon. | integer | 300 | How long, in seconds, with no keyboard, mouse or trackpad input before kcode.presence() and core.app.presence-changed count the user as idle. Restart-only. |
| session_daemon. | integer | 1000 | How often, in milliseconds, the daemon reads the Mac (its idle time, the lock screen and which kcode windows are on screen) while a plugin of some session watches core.app.presence-changed. With none watching it reads nothing. Never more often than every 100 ms. Restart-only. |
| session_daemon. | integer | 200 | Cap on the project-scoped prompt-history row (the composer's ↑/↓ recall list, persisted in <project>/.kcode/storage.db and surviving restarts): the newest this many submitted prompts/commands are kept. Restart-only (the daemon reads it once at boot). |
| session_daemon. | integer | 3 | Cap on per-session restart-storm respawns within the restart window: a session whose agent runner keeps crashing is respawned at most this many times per window, then left stopped with an error. Guards process respawns: distinct from the doom-loop guard, which detects repeated identical tool calls inside a turn. Restart-only. |
| session_daemon. | integer | 60 | The restart-storm window length in seconds (pairs with restart_max_per_window). Restart-only. |
| session_daemon. | integer | 30000 | GPU/daemon build only: how long (milliseconds) a freshly-spawned daemon waits for its first client to connect before giving up and exiting. Guards against an orphaned daemon that never gets a client (e.g. the spawning app died during launch). Restart-only. |
| session_daemon. | boolean | false | Whether the daemon binds the loopback webhook listener. On (with at least one webhook_tokens entry) POSTs to http://127.0.0.1:<webhook_port>/webhook/<name> fire the webhook:<name> trigger event: project [[hooks]] with on = "webhook:<name>" and plugin kcode.on_event("webhook:<name>", …) handlers hear it (Observe intent; the body never reaches a session: a hook it fires runs its own line as written, and the socket-trusted kcode trigger remains the only outside sender whose text reaches the agent). The body is read by its Content-Length; a chunked body is refused with 501. Public exposure stays the user's own tunnel. Restart-only (daemon-read). |
| session_daemon. | integer | 1048576 | The largest request body the webhook listener takes, in bytes; a longer declared Content-Length is refused with 413 before the body is read. Restart-only (daemon-read). |
| session_daemon. | integer | 16384 | The largest request head (request line and headers) the webhook listener reads, in bytes; a longer one is refused with 431. Restart-only (daemon-read). |
| session_daemon. | integer | 4517 | The webhook listener's port on 127.0.0.1 (the bind address is fixed at loopback). Restart-only (daemon-read). |
| session_daemon. | integer | 10 | How long one webhook request may take (reading it, firing its hooks and replying) before the listener closes its connection, in seconds. Restart-only (daemon-read). |
| session_daemon. | table? | {} | Shared-secret token per trigger name: [session_daemon.webhook_tokens] deploy = "s3cret". The allowlist: only named entries are fireable, each POST authenticating with Authorization: Bearer <token> (or ?token= for senders that cannot set headers); an undeclared name is 404, a wrong token 401. Empty (the default) refuses to start the listener even when enabled. Restart-only (daemon-read). |
| session_history | |||
| session_history. | integer | 262144 | Pending serialized display-record bytes that start a history commit. This is a batching threshold, not a limit that truncates content. Must be positive. Restart-only. |
| session_history. | integer | 64 | Pending display-record count that starts a history commit. Exchange and turn boundaries flush independently of this threshold. Must be positive. Restart-only. |
| session_history. | integer | 100 | Maximum age in milliseconds of the oldest pending display record before a history commit starts. A crash can lose the uncommitted live tail, never already committed history. Must be positive. Restart-only. |
| session_history. | integer | 8388608 | Combined serialized-byte budget for queued and pending history writes. One larger command can occupy the entire budget alone; it is never silently dropped. Must be positive. Restart-only. |
| session_history. | integer | 256 | Maximum queued history-writer commands per active turn. A full queue slows capture rather than dropping records. Must be positive. Restart-only. |
| session_panels | |||
| session_panels. | boolean | true | GPU client mode: auto-collapse older conversation turns so a growing live transcript stays focused on the current exchange. On by default: every turn except the two most recent folds to a clickable summary, a ▸ disclosure glyph, your instruction's first line, the reply's first line beneath it, and a dim · N tools tail; click the summary to expand the turn in full. A command you ran and its reply, and a ! shell command, are no part of a turn: they stay in view when the turn before them folds. Each line reads as the open turn shows it: bold, italic, links and code keep their look, with no Markdown marks; a heading, list item or quote shows its words, a code block its first line as code, and ends in an ellipsis where it is wider than the panel. The folded summary carries the reply's first line, so a folded transcript still reads as prompt → response exchanges: before this, the one-liner showed only the instruction, which on a resumed session (whose history is all older turns) read as 'all the model's replies vanished on restart'. An expanded turn carries its own ▾ collapse control in the left gutter (on the user message that opens the turn) click it to fold the turn back up; a just-finished live turn also carries the same ▾ on its ▣ model · elapsed completion footer. A per-turn click always overrides the policy for that turn, and jumping (⌘J or the Cmd-P picker) into a collapsed turn expands it. Set false to render every turn in full. Re-applied to live panels on a config.toml save. GPU build only. |
| session_panels. | boolean | true | GPU client mode: whether a settled chat message windows its own blocks, lays out only the paragraphs, code blocks and tables near the viewport and renders the rest as spacers of their recorded sizes, so one very long message costs a frame what the part on screen costs, not the whole message (scroll geometry and text selection are unchanged). On by default. Set false to lay every block of every message out on every frame: the escape hatch if a long message ever renders wrong, and what the scaling probe uses for its before/after table. Re-applied to live panels on a config.toml save. GPU build only. |
| session_panels. | float | 1.0 | GPU client mode: how far beyond the visible transcript a settled message still lays out for real, in viewports; 1.0 (the default) keeps one viewport above and one below ready, so a fast scroll lands on real blocks; 0.0 windows to the viewport alone (the cheapest frame, but a fling can show a block's placeholder for one frame before it lays out). Re-applied to live panels on a config.toml save. GPU build only. |
| session_panels. | string | "insert" | GPU client mode: the composer's editor mode, insert (default: every keystroke types, Escape peels the overlay stack) or vim (a modal composer: it boots in INSERT; Escape enters NORMAL where h/l/w/b/e/0/$/gg/G/f/t move, x/dd/D/cc/C/yy/p and d/c/y-plus-motion edit with a count prefix, i/a/A/o/O re-enter INSERT, u/ctrl-r undo/redo, Enter submits, and a NORMAL/INSERT chip sits above the composer; Escape in NORMAL cancels a half-typed command such as d or f, and otherwise still peels the overlay stack). Re-applied to live panels on a config.toml save. GPU build only. |
| session_panels. | float | 18.0 | GPU client mode: absolute chat transcript font size in points. Defaults to 18 pt; an explicit 0 follows the active theme: the theme body size plus the chat's +2 pt reading bump (17 pt on the bundled themes); a positive value pins every transcript message (prose, with code/math/headings scaled proportionally) to that size across all chat panels, and the metadata tiers (timestamps, captions, the status bar) scale by the same factor so they keep their proportion against the content. Adjust live from the settings page's General → 'Chat font size' stepper (half-point steps, 8–30 pt, Auto below the floor); re-applied to live panels on a config.toml save. GPU build only. |
| session_panels. | integer | 33554432 | Maximum serialized bytes in a chat's loaded history window. Independent of model context and the daemon's page budget. A single row above the limit reports an error rather than disappearing. Also bounds pending command receipts awaiting a save acknowledgement. Re-applied on a config.toml save. |
| session_panels. | integer | 512 | Maximum loaded display-history rows per chat. Older and newer pages load on demand; compaction never deletes original chat history. Visible and selected rows are protected from eviction; a completed click without selected text does not pin a row. Normal cache trimming does not block paging. If protection fills the window, scroll or clear the selection to retry, or choose Latest to release the selection and return to live output. Re-applied on a config.toml save; never changes model context. |
| session_panels. | float | 18.0 | GPU client mode: absolute composer (chat input) font size in points. Defaults to 18 pt; an explicit 0 follows the transcript size (or the active theme when that is also 0); a positive value pins the composer text size across all chat panels, independent of the transcript size. Adjust live from the settings page's General → 'Composer font size' stepper; re-applied to live panels on a config.toml save. GPU build only. |
| session_panels. | integer | 0 | GPU client mode: cap the chat composer's auto-growing height, in rows. 0 (default) is automatic: the composer grows with what you paste or type up to the larger of 12 rows or half the window height, then scrolls internally. A positive value pins the cap to that many rows regardless of window size. Re-applied to live panels on a config.toml save. GPU build only. |
| session_panels. | integer | 8388608 | GPU client mode: the largest http(s) image the window fetches for a chat message, in bytes (8 MiB). The read stops past it, whatever the server's Content-Length says, and the image shows its alt text. Read once when the window opens. GPU build only. |
| session_panels. | integer | 10 | GPU client mode: how long the window may take to fetch an http(s) image a chat message shows, in seconds; past it the image shows its alt text. Read once when the window opens. GPU build only. |
| session_panels. | integer | 150 | GPU client mode: how long (milliseconds) the reply smear takes to settle as the reply tip advances, each corner of the cursor quad is a critically-damped spring; this is its settle time. Larger = a longer, lazier trail. Live-reloads on a config.toml save. GPU build only. |
| session_panels. | string | "" | GPU client mode: the reply smear colour as a hex string ("#5B9EF9", the # optional). Empty (the default) rides the theme text colour: the reply smear's signature, distinct from the user caret smear (which rides the accent). A malformed value falls back to the text colour too. Live-reloads on a config.toml save. GPU build only. |
| session_panels. | boolean | true | GPU client mode: whether the reply smear draws, a Neovide-style animated cursor bar that trails the streaming reply's glyph tip through the chat as the agent's text lays out (and shows in the Mission Control grid tile miniatures too). The agent-output twin of the user's caret smear (session_presenter.cursor_smear.*), with its own independent knobs. On by default; set false for no reply cursor. Suppressed by the global animation switch (reduce-motion turns it off, since it auto-advances with the text). Live-reloads on a config.toml save. macOS/Metal only. GPU build only. |
| session_panels. | integer | 40 | GPU client mode: the reply smear's settle time (milliseconds) for a short, adjacent-glyph advance (a single token landing next to the last), kept snappy, as distinct from a long jump such as a line wrap (animation_length_ms). Live-reloads on a config.toml save. GPU build only. |
| session_panels. | integer | 100 | GPU client mode: the reply smear's trail length as a percent, 0–100. 100 (default) is the full Neovide smear: the trailing corner of the cursor quad lags farthest behind as the reply advances; 0 is no trail (a rigid bar). Values above 100 clamp to 100. Live-reloads on a config.toml save. GPU build only. |
| session_panels. | integer | 4 | GPU client mode: the reply smear bar's width in pixels, the opaque bar painted at the streaming glyph tip, behind the text. Live-reloads on a config.toml save. GPU build only. |
| session_panels. | boolean | false | GPU client mode: show control-plane status lines, the injected <cp:*> channel messages (e.g. the per-turn permission context), as dim status rows in the chat panel, arriving live on the control stream during a turn and decoded from the session buffer on a reload. Hidden by default, matching the terminal UI (which never shows them). Toggle live via /show-control; re-applied to live panels on a config.toml save. GPU build only. |
| session_panels. | boolean | false | GPU client mode: the default chain-of-thought (reasoning text) visibility for a session that has never run /cot (hidden by default). Gates only the reasoning text: the live ✦ Thinking… indicator shows regardless. A per-session /cot toggle overrides this and is persisted on the session row, so it is restored on --resume; re-applied to live panels on a config.toml save. GPU build only. |
| session_panels. | boolean | true | GPU client mode: show dim right-aligned timestamps on chat messages. Shown by default, matching opencode. A reply's time appears with its text, not while the model is still thinking. Times are written as 12-hour with an AM/PM marker. Every rendered time in the app goes through one shared vocabulary (message headers, the notification center, and the /stats and /debug “as of” footers), so no two surfaces can disagree. Toggle live via /timestamps; re-applied to live panels on a config.toml save. GPU build only. |
| session_panels. | boolean | true | GPU client mode: show tool-call bubbles (name + args + result) in the chat panel. Shown by default, matching the terminal UI; the agent invokes tools either way: this gates only the view. Toggle live via /show-tools; re-applied to live panels on a config.toml save. GPU build only. |
| session_panels. | string | "dot-matrix" | GPU client mode: which working-state ('thinking') animation the chat panel's busy strip plays while a turn is in flight, eight frame-driven styles (per-display-frame interpolation like the cursor smears, never tick-driven): dot-matrix (default, kcode's signature: the website's dot-matrix hero at strip scale, a 15×5 LED grid lit by the Mission Control backdrop's own noise field and sweep, showing a pictogram of the turn's phase, a brain-wave trace scrolling across while the model thinks, < and > with a bar turning between them while a tool runs, an LED lit for each word of the reply as it arrives, fading over about a second, a fork with one lit branch per running agent, a bar collapsing inward while compacting, amber pause bars while the turn is parked on you, a single slow-blinking standby LED through a provider retry, and a checkmark that reveals, holds and fades over ~0.9 s when the turn completes (none when it ends in an error); the field's shimmer follows event recency, idling as a stall grows), dots (the chat-native typing indicator: three accent dots rising and fading in a staggered wave), equalizer (five audio-meter pill bars dancing on two incommensurate sines), sweep (a Larson-scanner accent head bouncing along a short track, towing a Gaussian trail), orbit (a dot circling a ··· ellipsis), hairline (a 1px gradient line whose bright centre slides with a Gaussian falloff), nebula (a faint accent bloom in the panel backdrop, fading on the first streamed token), and comet (an accent glow travelling the composer's L-frame). An unknown value falls back to dot-matrix. With animations off, every style renders its static first frame (the dot matrix: the phase's resolved picture, and no post-turn checkmark linger). Cycle it live from the settings page's General → 'Working animation' row; re-applied to live panels on a config.toml save. GPU build only. |
| session_panels. | string? | macOS open (file associations) | GPU client mode: the command used to open a file clicked in /files, tool/LSP results, or markdown. File links are enabled only after a background check finds a usable handler. A click rechecks it, acknowledges the launch with the app name, and reports any failure; an acknowledgement is not proof of a visible editor window. Quoted executable paths and arguments are supported. The clicked file's absolute path is appended to the command, or substituted for a {} placeholder if the command contains one; an LSP row also carries a 1-indexed line, so a bare known editor gets its line-jump argument appended (VS Code-family via --goto file:line, Zed/Sublime via a positional file:line) and a {line} placeholder is substituted where you place it (e.g. code --goto {}:{line}). A /files click carries no line and opens the whole file. When unset, the file opens via macOS open, which respects your per-extension file associations, so a click opens the file in the app you actually use, never a terminal editor or GUI shim kcode happened to find on PATH first. open cannot target a line, so set this to a line-aware editor (e.g. code) if you want LSP-row jumps to land on the line. An image file (png/jpg/gif/etc.) opens via session_panels.files.image_editor instead. An all-session setting editable on the Settings page (Advanced › Editor); captured at startup, so restart-only. GPU build only. |
| session_panels. | string? | (macOS Preview) | GPU client mode: the command used to open an image file clicked in the /files overlay, named by extension (png, jpg, jpeg, gif, webp, bmp, tiff, ico, heic, svg). Same command-line shape as session_panels.files.editor (the file's absolute path is appended, or substituted for a {} placeholder). When unset, images open in macOS Preview (open -a Preview). An all-session setting editable on the Settings page (Advanced › Image opener); captured at startup, so restart-only. GPU build only. |
| session_presenter | |||
| session_presenter. | integer | 30 | GPU client mode: how often decorative motion repaints, in frames per second, a chat panel's busy-turn pump (the tool spinner, the working-state animation, the stall clock, the dot-matrix done linger), the paint of streamed reply text (a burst of provider deltas inside one period lands in one paint; the text arrives whole, and every other turn event (a tool starting, the turn ending) paints at once), the reply smear, the empty-grid invitation's breathing pulse, and Mission Control's tile breath + ambient backdrop shader pump. Every one of these reads the wall clock, so a lower rate changes only how many frames they cost, not how fast they move; interaction transitions (the wordmark fade, text-selection auto-scroll) and the global caret smear stay at display rate. 0 = every display frame (120 a second on a ProMotion display). Default 30: the motion reads as continuous while a live turn's redraw work drops to a quarter of display rate. The chat in the main view (the maximized tile or split, or the selected row or tab in Sidebar and Tabbed) moves at session_presenter.chat_frame_rate instead; every other chat panel, the grid's miniatures and subagent tiles outside the main view move at this rate. Cycle it live from the settings page's General → 'Motion frame rate' row (15 → 24 → 30 → 60 → Display rate); live-reloads on a config.toml save, diff-gated. GPU build only. |
| session_presenter. | bool? | true | GPU client mode: the one switch for every animation in the app, the in-flight tool spinner, the global caret smear and the per-chat reply smear, the grid miniature pumps, the context menu's open/close ease, the underlay hints' breathing pulse, the notification drawer's slide, and the ambient backdrop shader. Off renders each of them static at rest (the spinner becomes a still '⋯', the smears jump instead of trailing, the hints sit at full presence, the shader freezes on the frame it was showing) and stops the frame requests that drove them, so nothing shifts position between the two modes. On unless you set it to false. kcode does not follow macOS's Reduce motion setting (System Settings → Accessibility → Display); set this key instead. Motion sensitivity is also why it is one setting rather than a per-animation matrix. Switching directly between sessions within Focused, Sidebar, or Tabbed mode is always immediate: the destination appears at its final size, without shrinking and rewrapping live conversations. Entering or leaving the grid, changing layout mode, and rearranging focus groups still animate when this setting is on. Flip it live from the settings page's General → Animations toggle or the ⌘P palette's 'Toggle animations': both persist here, so the choice survives a relaunch. Live-reloads on a config.toml save, diff-gated so an unrelated save never clobbers a runtime toggle. |
| session_presenter. | string | "adaptive" | GPU client mode: how fast the chat in the main view moves, the maximized tile or split, or the selected row or tab in Sidebar and Tabbed: its streamed reply text, the working animation, the stall clock and the reply smear. adaptive (the default) starts at display rate (120 frames a second on a ProMotion display) and steps to 60 and then 30 when the window's draws take most of a frame, stepping back up once they fit with room to spare for 2 seconds; a change of view starts it again at display rate. 60 and 30 hold that rate whatever the draws take. Every other chat panel moves at session_presenter.animation_fps. Cycle it live from the settings page's General → 'Chat frame rate' row in the Advanced view (Adaptive → 60 fps → 30 fps); live-reloads on a config.toml save, diff-gated. GPU build only. |
| session_presenter. | integer | 150 | GPU client mode: how long (milliseconds) the smear takes to settle on a long jump, e.g. from the chat input to a picker row. Each corner of the cursor quad is a critically-damped spring; this is its settle time. Larger = a longer, lazier smear. Live-reloads on a config.toml save. GPU build only. |
| session_presenter. | string | "" | GPU client mode: the smear colour as a hex string ("#5B9EF9", the # optional). Empty (the default) rides the theme accent colour: the caret smear's signature as your cursor, distinct from the reply smear (which rides the text colour); a malformed value falls back to the accent too. Live-reloads on a config.toml save. GPU build only. |
| session_presenter. | boolean | true | GPU client mode: whether the global cursor smear draws, a Neovide-style trail on the text caret that follows it wherever it moves, including jumps between the chat input and the overlay pickers (Cmd-K switcher, Cmd-P palette, / slash menu). A session change resets the smear: it lands at the new session's caret rather than trailing across unrelated composers. On by default; set false for a plain caret. Also honours the global animation switch (reduce-motion turns it off regardless). Live-reloads on a config.toml save. macOS/Metal only. GPU build only. |
| session_presenter. | integer | 40 | GPU client mode: the settle time (milliseconds) for a short, adjacent-glyph caret move (typing), kept snappy so per-keystroke motion doesn't feel laggy, as distinct from a long region jump (animation_length_ms). Live-reloads on a config.toml save. GPU build only. |
| session_presenter. | integer | 100 | GPU client mode: the smear's trail length as a percent, 0–100. 100 (default) is the full Neovide smear: the trailing corner of the cursor quad lags farthest behind on a move; 0 is no trail (the cursor jumps rigidly). Values above 100 clamp to 100. Live-reloads on a config.toml save. GPU build only. |
| session_presenter. | integer | 4 | GPU client mode: the smeared caret bar's width in pixels, an opaque bar drawn over the native caret (about twice a typical 2px caret, so the smear reads clearly). Live-reloads on a config.toml save. GPU build only. |
| session_presenter. | string | "Grid" | The layout the Mission Control window opens in before a persisted workspace loads: Grid | Focused | Tabbed | Sidebar (Sidebar: the macOS split view, a 280 px rail, at most a third of a narrow or zoomed-in window, lists sessions with status dots and model/state subtitles; ⌘⇧B collapses it to 48 px, saved with the workspace. Tabbed uses a horizontally scrolling 40 px strip, an accent underline, close controls and a + button opening the same directory picker as ⌘N. Both support drag reorder and keep the selected pane interactive; the rail or strip scrolls to show the selected session's row or tab when you switch to the layout, select another session or move the selected one; a name too long for its row or tab is cut to one line with …, and resting the pointer on it shows the whole name; and both draw each session's dot as /stats all and ⌘K do: filled while a turn runs, hollow at rest, dotted once stopped, coloured by state, green after a turn that finished while you were elsewhere, until you open the session). The GPU window is the only frontend. Cycle the live layout from the settings page (⌘,), the ⌘P palette, or the right-click context menu. |
| session_presenter. | string | "app" | GPU client mode: which directory picker ⌘N (and the context menu / palette 'New session') opens for a new session. "app" = the in-app folder picker (an Up button and a clickable path, favorites, recents, a scratch session, inline new-folder creation: see the Cmd-N shortcut); "native" = the macOS folder dialog (NSOpenPanel). Switched live from Settings (⌘,) › General › Directory picker (a cycle row) and read fresh on every open, so a flip applies to the very next ⌘N; a direct config edit applies the same way (no restart, though the key is only read client-side at picker-open time). GPU build only. |
| session_presenter. | integer | 8 | GPU client mode: how far (px) a press must move on a Mission Control tile before it arms a drag. gpui's built-in default is 2px, so a click that jitters a few pixels between press and release is swallowed as a drag and never opens the session; the default 8 keeps a slightly-imperfect click on an unzoomed tile a click (maximize) while a deliberate drag still reorders/groups. Restart-only. GPU build only. |
| session_presenter. | array | [] | GPU client mode: the in-app directory picker's starred directories, the sidebar's Favorites section. Absolute paths; a leading ~ is expanded for hand-edited entries. Written as the whole list every time a directory is starred/unstarred in the picker (⌘D or the row star), so the file always mirrors the picker. GPU build only. |
| session_presenter. | array | [] | GPU client mode: the model picker's starred models, floated to a top ★ Favorites section in the /model picker and Settings › General › Default model. ⌘D stars the highlighted row as <provider>:<model>, so a model several providers list is starred under the provider it was starred from, and only that row moves out of its provider's section; a bare model id written by hand stars the first row that lists it, connected providers first. Written as the whole list every time a model is starred/unstarred with ⌘D, so the file always mirrors the picker; hand-editable. A favourite the catalogue no longer lists simply drops from the section. GPU build only. |
| session_presenter. | integer | 60000 | GPU client mode: how long (milliseconds) a turn works before the one-time long turn tip shows in the session you are in, the row above the composer teaching ⌘N for another session and the notification drawer on the right edge. It shows once per user (the seen set lives in the user store), then never again. 0 fires at the first tick of a working turn. Restart-only. GPU build only. |
| session_presenter. | string? | (theme default) | GPU client mode: the mono (code) font family code blocks, diffs, and tool output render in. Unset = the active theme's authored mono family (Menlo). Set it live from the Settings page's General → Mono font picker (a searchable list of every installed font, plus “Theme default”); the pick persists here and re-installs the active theme at once. The binary maps it onto Wingman's theming.mono_font_family. A hand-edit of this key applies on restart. GPU build only. |
| session_presenter. | boolean | true | GPU client mode, macOS only: keep the window out of App Nap while any session is working. App Nap slows an app that has been hidden or covered for about a minute, and the daemon requests the window's queued messages before every provider call, so a napped window slowed every round of a turn: a 30-round turn took 3.2 s instead of 0.7 s. While at least one session works, a turn, a compaction or its subagents running (a turn waiting on your answer does not count), the window holds an NSProcessInfo user-initiated activity that still lets the Mac idle-sleep, and ends it the moment no session works: the window's twin of session_daemon.keep_awake. Off, a hidden window naps whenever macOS decides. Restart-only. GPU build only. |
| session_presenter. | string | "sidebar" | GPU client mode: the settings page's navigation layout. "sidebar" = the macOS-System-Settings left rail of sections (the default); "tabs" = a horizontal tab bar under the title. Same sections, selection, and keyboard drive either way (↑/↓ move the selection; in the tab-bar layout ←/→ also move it, → moves the tab, and Enter alone dives into a section's rows). Switched live from Settings (⌘,) › General › Settings navigation, in the Advanced view (a cycle row: an open page re-lays out in place) and read fresh on every open, so a direct config edit applies to the next settings open. GPU build only. |
| session_presenter. | string | "shader" | GPU client mode: which one thing paints behind the Mission Control grid, shader (the ambient shader named by shader.background, the dot-matrix LED field ported from the kcode website), image (the still at shader.background_image), video (the loop at shader.background_video), or off (the plain themed background; the per-tile light and reactive feed stand down too). One explicit choice: the image and video paths keep their values while not chosen (the Settings rows say not in use), so switching back needs no re-pick. Picking an image or video on the Settings page chooses it; cycling the backdrop style chooses the shader; clearing the chosen file falls back to the shader. A chosen image or video that can't be read (missing, unreadable, not a format the decoder accepts) is a fallback, not a reset: the shader paints instead, the row says can't be read, and a notice names the file and the reason; the grid never goes dark without saying why. Cycle it live on the Settings page's General → Backdrop (Shader / Image / Video / Off); a config-save re-applies it without a restart. GPU build only. |
| session_presenter. | string | "dot-matrix" | GPU client mode: which shader is the ambient backdrop while shader.backdrop = "shader", a bundled built-in name (dot-matrix, the LED-grid field ported from the kcode website, which also lights shader.wordmark into its dots on the empty grid) or the stem of a ~/.kcode/shaders/<name>.glsl Shadertoy-style file you've dropped in. Cycle it on the Settings page's General → Backdrop style (which also chooses the shader backdrop), or set it here; a config-save re-applies live (the config value is watched; the shader source file itself is read once on select, not hot-watched). A name that doesn't resolve (a removed built-in, a typo, a missing file) falls back to dot-matrix with a warning in the log rather than leaving the grid dark. Unset paints no backdrop. The row says not in use while an image or video is the backdrop and showing as fallback while the shader paints in place of a chosen file that can't be read. GPU build only. |
| session_presenter. | string? | (none) | GPU client mode: an absolute path to a still image (PNG/JPEG/…) painted cover-fit behind the Mission Control grid while shader.backdrop = "image", a wallpaper for the control room. While it shows, the ambient background shader (and its wordmark) stand down (the bundled shaders paint opaquely and would hide it); the per-tile light and post-process still run. The path is kept while another backdrop is chosen (the Settings row says not in use). A file that can't be read leaves the shader painting as the fallback, marks the row can't be read, and posts a notice naming the file and the reason: the grid never goes blank over a bad path. Grid mode only: a maximized chat never shows it. Pick it on the Settings page's General → Background image (a native file dialog; a pick also chooses the image backdrop). The selected filename appears immediately with Loading image… / Preparing image… / Saving image… feedback. Reading, decoding, display-sized texture preparation, and copying run on a worker, not the UI thread; the app stays interactive. The old background and saved choice remain until the new image succeeds. A failed replacement keeps the working background and explains why. Picking again or changing/clearing the backdrop cancels the older result. A picked file is copied into a private import directory under ~/.kcode/backdrops/image/, retaining its basename, and the copy's path is what this key keeps: the dialog's permission to read a file under a macOS-guarded folder (Dropbox and other cloud-storage mounts, Desktop, Documents, Downloads) lasts only for that launch, and the copy stays readable at every launch. One copy at a time: a new pick replaces it, and clearing the row removes it; a path written here by hand is used as it is and never removed. If the copy fails, the picked file is used in place and a notice says so. Clear it with the row's ✕ (or Backspace / Delete on the selected row), which falls back to the shader when the image was the backdrop, or by removing the key. A config-save re-applies live. GPU build only. |
| session_presenter. | string? | (none) | GPU client mode: a video file (MP4/MOV/…) played muted and looping, cover-fit behind the Mission Control grid while shader.backdrop = "video". Pick it in Settings → General → Background video. The filename appears immediately with Copying video… / Preparing video… / Waiting for first frame… feedback. File checks, copying and asset loading run on a worker; the main-thread player remains a candidate until its first decoded frame. Only then does the new selection replace the current backdrop and saved choice. A failed or timed-out replacement keeps the working backdrop and explains why; corrupt and audio-only files are rejected. If no backdrop is available, the shader remains visible. The loading deadline is shader.video_load_timeout_ms. A newer image or video pick, Clear, a backdrop switch or a relevant config reload cancels obsolete work. Picked videos are staged into private import directories under ~/.kcode/backdrops/video/, retaining their basenames; old managed copies are removed only after acceptance. The copy remains readable after the file dialog's read grant expires. A failed copy may use a successfully validated source in place with a warning. A hand-written path is never copied or removed. Both media paths are kept while another backdrop is selected. Once the first frame is ready, hidden or motion-off playback pauses on a held frame; later playback failures keep the last good frame and report why. The ambient shader and wordmark stand down only when a frame is available; per-tile light and post-process still run. Clear with the row's ✕ (or Backspace / Delete), falling back to the shader if video was selected. Config-save changes apply live. macOS GPU build only. |
| session_presenter. | boolean | true | GPU client mode: whether each session tile in the grid carries its own reactive light field (a calm coloured light around the frosted tile) a reactive edge-glow plus an animated field in the margins, that brightens with that session's activity, shifts toward the theme's warning colour as its context window fills, quickens with its reasoning effort, and turns the theme's waiting or error colour when it needs you. Painted per tile (Grid mode only) from each session's own live state, distinct from the single grid-wide ambient backdrop. Stands down (the row says not in use) while shader.backdrop = "off". Toggle it live on the Settings page's General → Per-tile activity light. GPU build only. |
| session_presenter. | string? | (none) | GPU client mode: an optional full-window post-process shader run over the composited frame (same built-in-name-or-~/.kcode/shaders/*.glsl resolution as the background). Unset (the default) means no post pass. No settings-page control yet; set it here, and a config-save re-applies live. GPU build only. |
| session_presenter. | boolean | true | GPU client mode: whether the ambient backdrop reacts to live session state, brightening with the grid's mean activity, warming when a session needs you, and blooming when a turn completes. When false the backdrop still paints but is fed a zeroed, static state. Stands down (the row says not in use) while shader.backdrop = "off". Toggle it live on the Settings page's General → Backdrop reacts to activity. GPU build only. |
| session_presenter. | integer | 30000 | Maximum time in milliseconds for a background-video selection to produce its first decoded frame, including copying and asset preparation. On expiry, the loading indicator stops, late results are rejected, and the current backdrop and saved choice are kept with an explanatory notice. Zero is clamped to one millisecond, not an unlimited wait. Applies to the next load; live-reloads with the shader settings. A blocked file read may finish later on the worker but never holds the UI thread. |
| session_presenter. | string? | your first name (kcode before sign-up) | GPU client mode: the text the dot-matrix backdrop lights into its LEDs on the empty Mission Control grid, the kcode website's hero, where the dots spell the name. Unset, it spells the first name this Mac was signed up with, in lower case and at most 16 letters (ada for Ada Lovelace), and kcode until you sign up; the name itself is never written to config.toml. It fades out once the first session tile lands and back in when the grid empties, and the empty-grid invitation drops its own logo and sits below it while it shows. Blank ("") means no wordmark (the invitation then carries the brand itself). Only meaningful while a background shader is painting: with an image, a video, or nothing chosen as shader.backdrop, nothing reads it (the Settings row says not in use). Edit it on the Settings page's General → Backdrop wordmark, which shows your first name until you type another; a config-save re-applies live. GPU build only. |
| session_presenter. | integer | 5000 | GPU client mode: how long (milliseconds) the single-session '⌘N to start another session' underlay hint lingers before it auto-dismisses, so it teaches the spawn gesture once each time the grid drops to a lone tile instead of being a permanent fixture. It re-shows on the next entry into the single-tile state. 0 keeps it up for as long as one tile remains. Does not affect the zero-session empty-state invitation, which is always shown. Restart-only. GPU build only. |
| session_presenter. | integer | 3 | GPU client mode: in the project-first historical sessions (⌘K), how many of a drilled-in project's most-recent stopped sessions show before the 'show older' toggle row. Keeps a project with a long history to a short list. Live off-grid sessions (RUNNING) are always shown in full; only the stopped pile is capped, and typing a search bypasses the cap (it spans the whole history). Restart-only. GPU build only. |
| session_presenter. | int? | unset | GPU client mode: the resting Mission-Control tile's backdrop-blur radius in px. Unset = follow the active theme's authored tile_blur (the default: the theme owns the frost); 0 = clean glass (no blur, just the translucent tint over the backdrop); n = that blur radius. Separate from tile_opacity so you can keep the glass look while dropping the blur-tint. Applies to a tile at rest only. Adjust it live on the Settings page's General → Tile blur stepper (4 px steps; below 0 steps back to Auto, 0 shown as Off); a config-save re-applies it too. GPU build only. |
| session_presenter. | integer | 0 | GPU client mode: the resting Mission-Control tile's translucency, as a percent. 0 = follow the active theme's authored tile_rest_opacity (the default: the theme owns how much an idle card recedes into the ambient backdrop); 1–100 overrides it (lower = more of the ambient shader/background shows through). Applies to a tile at rest only: hover, maximize, and an attention glow still solidify to fully opaque, so the engagement cue is never lost. Adjust it live on the Settings page's General → Tile opacity stepper (5% steps, 0 shown as Auto); a config-save re-applies it too. GPU build only. |
| session_presenter. | string? | (theme default) | GPU client mode: the UI font family every proportional text role renders in, chat body, titles, captions, chrome, overlays. Unset = the active theme's authored family, which is now a monospace family (Menlo): kcode's whole interface renders monospace by default (matching a terminal coding agent); set this to any proportional family to override. Set it live from the Settings page's General → UI font picker (a searchable list of every font installed on your machine, plus a “Theme default” option to clear the override); the pick persists here and re-installs the active theme so the new font applies at once. The binary maps it onto Wingman's theming.ui_font_family so the window opens in your font. A hand-edit of this key applies on restart. GPU build only. |
| session_presenter. | integer | 100 | GPU client mode: the window zoom, as a percent (100 = actual size). It magnifies everything in the window (text, panels, spacing and images) the way a browser zooms a page, so a layout keeps its proportions at any size. The window opens at it. Change it live with ⌘+/⌘− (⌘0 resets to 100) or the Settings page's General → Zoom stepper (50–200%, 10% steps); each change persists here. A value outside 50–200 is held to the nearest end. A hand-edit of this key applies on restart. GPU build only. |
| shell_client | |||
| shell_client. | integer | 86400000 | Documented only by its default. Run kcode config defaults for the full table. |
| shell_client. | integer | 5000 | Documented only by its default. Run kcode config defaults for the full table. |
| shell_client. | integer | 256 | Documented only by its default. Run kcode config defaults for the full table. |
| shell_client. | integer | 2000 | Documented only by its default. Run kcode config defaults for the full table. |
| shell_client. | integer | 2 | Documented only by its default. Run kcode config defaults for the full table. |
| shell_client. | integer | 30000 | Documented only by its default. Run kcode config defaults for the full table. |
| shell_host | |||
| shell_host. | int? | none | Default wall-clock budget for shell.exec when the request omits one. Unset waits indefinitely (the bash tool has its own tool_bash.default_timeout_seconds on top). |
| shell_host. | integer | 50 | Lines of head/tail preview in each shell result; the full stream stays in the host's output stash. Applies inside the re-exec'd shell host, so it covers bash and every shell.* tool. |
| shell_host. | integer | 500 | How often each running command's per-pid resources (cpu/rss/io) are sampled for the run footprint shown on bash results. 0 disables sampling. |
| skill_exec | |||
| skill_exec. | integer | 67108864 | The most memory a script skill's run.lua may allocate (64 MiB); an allocation past it fails the run with an error naming this setting. 0 = no limit. Restart-only. |
| skill_exec. | integer | 60 | How long a script skill's run.lua may take to load and run, in seconds; a script still running then (busy in a loop or waiting on kcode) is stopped, and the run fails with an error naming this setting. Time a permission prompt or question stays open doesn't count. Restart-only. |
| skill_framework | |||
| skill_framework. | boolean | true | Follow symlinks encountered while walking a skill_dirs directory. On by default so a centrally-managed setup (where individual skill files or skill directories under ~/.kcode/skills are symlinks into a shared repo) resolves to the real files. A symlinked root skills dir is followed regardless; this governs symlinks met during the walk. Restart-only (a deep lib [section] knob). |
| skill_framework. | boolean | true | Documented only by its default. Run kcode config defaults for the full table. |
| skill_framework. | boolean | true | Documented only by its default. Run kcode config defaults for the full table. |
| snapshot | |||
| snapshot. | array | [ "*.log", "node_modules/" ] | Paths the /undo turn records leave out beyond the project's .gitignore, .ignore and .rgignore, in gitignore syntax read from the project root: *.log at any depth, node_modules/ a folder, /dist at the root only; a later !pattern keeps what an earlier one left out. /undo neither puts back nor removes a path the list left out when the turn started or ended, even once the list changes. Version-control folders (.git, .hg, .jj, …) and kcode's own files in any .kcode folder (its database, worktree checkouts, build folders, skill state and /share exports) are always left out, whatever this list says, and so are the notes folder .notes/ at the project root and kcode's data dir and snapshot store when they sit inside the project; the rest of a .kcode folder is recorded like any other file. Default ["*.log", "node_modules/"]. |
| snapshot. | integer | 3600 | How long (seconds) an unreferenced snapshot blob is kept before a collection deletes it. A capture in another process may have written its blobs but not yet the manifest naming them; the grace covers that window. Default 3600. |
| snapshot. | integer | 300 | The least time (seconds) between two blob collections of one project. A collection runs after a retention prune removed a manifest, and no more often than this; the snapshot gc log line reports each one. Default 300. |
| snapshot. | integer | 100 | The largest file, in MiB, the /undo turn records hold. A bigger file is noted but not stored, and /undo neither puts it back nor removes it. Default 100; 0 = no limit. |
| snapshot. | boolean | true | Whether the /undo turn records leave out what the project's .gitignore files ignore. The project's .ignore and .rgignore files are followed either way. /undo neither puts back nor removes a path left out when the turn started or ended. Default true. |
| snapshot. | integer | 50 | How many turn records and how many per-edit records one project keeps, each against its own cap, across all its sessions: the oldest beyond the cap are pruned after each record (never a running turn's start record or the per-edit records made since it began) a turn's end record goes with its start record, and the blobs only the pruned records named are collected afterwards. /undo walks back only as far as the turns kept. Default 50; 0 = keep everything. |
| startup_trace | |||
| startup_trace. | float | 3000.0 | Start-up total (milliseconds) above which the always-on start-up phase summary of the GPU client, the drive client or the daemon logs at warn (naming the stalled phase) instead of info: the slow-start self-diagnosis in the daily log. Each reads it once per launch, when its start is complete. |
| subagent | |||
| subagent. | boolean | true | Switch for the advisor tool (a read-only sub-agent the model calls for a second opinion). On by default, but the tool is offered only once subagent.advisor_model is set; off removes it even then. Restart-only (read at stack build). |
| subagent. | string? | (unset) | The model the advisor tool runs on. Settings › Subagents › Advisor model picks it from a list, and its No advisor row unsets it; by hand it is a <provider>:<model> reference, a full model id or a catalogue display label. It must differ from the calling session's model (a same-model call is refused: a second opinion from the same model is no opinion). Unset (the default) offers no advisor: kcode never picks its model itself, and the agent is not given a tool that could only fail. A model no connected provider serves is refused when the tool runs. The sessions started next use a change; a running session keeps the advisor it started with. |
| subagent. | integer | 10 | The most subagents one session runs at once, nested ones included: a chain of nested subagents holds one place per level. A spawn past it is refused, and the agent is told to wait for one to finish. 0 lets no subagent start. Restart-only (read at stack build). |
| subagent. | integer | 5 | How deep subagents nest: one the session's own agent starts is 1 deep, one that subagent starts is 2. A spawn past it is refused, and the agent is told to do the work itself. 0 lets no subagent start. Restart-only (read at stack build). |
| subagent. | integer | 240 | Documented only by its default. Run kcode config defaults for the full table. |
| tool_ask_model | |||
| tool_ask_model. | integer | 20 | The most images one ask_model call sends; a call naming more is refused. Applies to new sessions. |
| tool_ask_model. | integer | 12582912 | The most bytes the images of one ask_model call take together; a call whose images pass it is refused. Keeps a request well under a vendor's limit (Anthropic's is 32 MB). Applies to new sessions. |
| tool_bash | |||
| tool_bash. | integer | 120 | Wall-clock budget for a bash tool call that doesn't pass its own timeout. On expiry the command keeps running in the background and the result says so: nothing is killed. |
| tool_bash. | integer | 20480 | The bytes of each output stream (stdout, stderr) a bash result returns when the call sets no max_output_bytes, and the tail size shown for user-run! commands. A longer stream keeps its first quarter and last three quarters around a line naming the bytes left out and the shell_output_slice call that returns them. Full output stays in the shell host's stash, readable via shell_output_* tools. |
| tool_bash. | boolean | true | Carry shell state across bash calls like one continuous terminal: each run's cd and exported-env changes (including sourced activations like a venv) fold into the calling agent's own overlay, which its next bash/shell_spawn seeds from. Each agent keeps its own: the session's agent (whose shell the user's ! commands share), each subagent run, starting in the project or its worktree, with none of its parent's changes, and dropped when the run ends, and each plugin. The engine still builds a fresh shell per command: only cwd and exported vars carry. A single call opts out with fresh_state: true; set false to restore fully stateless calls (the agent then carries state by passing a result's cwd_change/env_changes back via the cwd/env args). |
| tool_bash. | integer | 200 | Live output/status refresh interval for user-run! commands. Effective minimum 50 ms; applies to newly created session runtimes. |
| tool_bash. | integer | 5000 | How long a user-run! command waits for Stop confirmation before reporting an unknown outcome. It is never automatically retried. |
| tool_fs | |||
| tool_fs. | integer | 1048576 | The most bytes one fs_read returns. A longer file is cut at a whole line and says so; page the rest with offset and limit. Applies to new sessions. |
| tool_fs. | integer | 1000 | The most files one fs_glob call lists, the first in sorted order; the result counts the files left out. At least 1. Applies to new sessions. |
| tool_fs. | integer | 1048576 | The largest file fs_replace reads, in bytes; a larger file is passed over and counted under the preview's skipped files. Applies to new sessions. |
| tool_fs. | integer | 1000 | The most files one fs_replace changes; a preview that would change more is refused, naming the limit. At least 1. Applies to new sessions. |
| tool_fs. | integer | 50 | The most sample lines one fs_replace preview shows in all, given to the files in path order, at most three each; the preview says when it left samples out. Applies to new sessions. |
| tool_grep | |||
| tool_grep. | integer | 1000 | The most lines one grep search returns, counting each match once for its own line and once for each context line asked for; the first matches and the last are kept, and omitted counts the rest. A search keeps at least one match. Applies to new sessions. |
| tool_tests | |||
| tool_tests. | integer | 524288 | Maximum bytes read from each manifest by test_discover. Oversized files are reported, not executed. Applies to new sessions. |
| tool_tests. | integer | 50 | Maximum failure names returned by test_status; reports when more were observed. Applies to new sessions. |
| tool_tests. | integer | 128 | Maximum test-run handles retained per session (minimum one). Completed runs are pruned oldest-first; active runs are never forgotten to make room. Handles do not survive session reload. Applies to new sessions. |
| tool_tests. | integer | 50 | The most test files test_discover lists for one runner; it marks a runner whose list it cut as truncated. Applies to new sessions. |
| tool_tests. | integer | 16384 | Maximum bytes in a test_output page or each test_status preview. Full captured logs stay in the shell output store, subject to its retention. Applies to new sessions. |
| tool_tests. | integer | 16777216 | Maximum bytes of JUnit XML reports test_status reads for one run, all its reports together. A run whose reports hold more is incomplete, never passed. Applies to new sessions. |
| tool_tests. | integer | 262144 | Maximum bytes read per test-output stream for result interpretation. A truncated log cannot prove a test pass. Applies to new sessions. |
| tool_vision | |||
| tool_vision. | integer | 20 | The most images one view_image call returns one by one, and the most pages one read_pdf call draws as images; a longer view_image list is refused, and pointed at sheet: true when a sheet would hold it, and read_pdf names the pages past it under left_out. Applies to new sessions. |
| tool_vision. | integer | 536870912 | The largest PDF read_pdf reads, in bytes; a larger file is refused before it is read. Applies to new sessions. |
| tool_vision. | integer | 262144 | The most bytes of text one read_pdf call returns. The page that would pass it and every one after it are left out, named under left_out for the next call; a first page that alone passes it is cut. Applies to new sessions. |
| tool_vision. | integer | 100 | The most images, or PDF pages, one contact sheet (sheet: true) tiles into its one image; a longer view_image list is refused, and read_pdf names the pages past it under left_out. Applies to new sessions. |
| tool_vision. | integer | 12582912 | The most bytes the images of one view_image or read_pdf call take together, in bytes. A view_image list leaves out, unread, the image that would pass it and every one after it, naming each under failed; read_pdf names the pages it leaves out under left_out; a sheet is written within it. Keeps a request well under a vendor's limit (Anthropic's is 32 MB). Applies to new sessions. |
| tool_web | |||
| tool_web. | integer | 1048576 | web_fetch output cap; output beyond it is dropped with a truncation marker. A raw or non-HTML body is read only up to this size, so a larger or endless body is never held whole. Restart-only. |
| tool_web. | integer | 30 | Per-request timeout for web_fetch (overridable per call via its timeout_ms argument, up to tool_web.max_timeout_secs) and web_search. Restart-only. |
| tool_web. | integer | 10485760 | The most bytes web_fetch reads of an HTML page it converts to Markdown (the Markdown is then capped at tool_web.default_body_cap_bytes; a page cut here is marked truncated), and the most web_search reads of a search API's answer: a larger answer is refused. Restart-only. |
| tool_web. | integer | 120 | The longest timeout the model may ask of web_fetch through timeout_ms; a longer one is cut to this, or to tool_web.default_timeout_secs when that is longer. Restart-only. |
| tool_web. | string? | none | API key for tool_web.search_provider. Env form KCODE_TOOL_WEB__SEARCH_API_KEY. If absent, runtime setup reads only the explicitly named provider's BRAVE_API_KEY, TAVILY_API_KEY, or EXA_API_KEY; an explicit empty key disables fallback. Every search backend maps to one normalized result shape (rank / title / URL / snippet), so switching providers changes nothing about what the model sees. Restart-only. |
| tool_web. | string? | none | Override the search provider's endpoint base URL (self-hosted gateways, proxies). Unset = the provider's public endpoint. Restart-only. |
| tool_web. | string | "advanced" | Tavily's search_depth: basic is one fast pass, advanced a deeper crawl with better-ranked, more relevant snippets, the default, at two Tavily API credits per call instead of one. Brave and Exa ignore it. Restart-only. |
| tool_web. | boolean | true | Ask Tavily for a short written answer to the query alongside the hits; the tool's text leads with it as Answer: and the structured result carries it as answer. Brave and Exa ignore it. Restart-only. |
| tool_web. | integer | 8 | Cap on results per web_search call. The tool's count argument may ask for fewer, never more. Restart-only. |
| tool_web. | string? | none | The web_search backend: brave, tavily, or exa (case-insensitive). The tool registers only when this is explicitly selected and a key resolves: tool_web.search_api_key first, otherwise that provider's BRAVE_API_KEY, TAVILY_API_KEY, or EXA_API_KEY. No key means no search tool. The provider must be named explicitly; a key with no provider (or an unknown name) skips registration with a startup warning rather than guessing which host to send the key to. Restart-only. |
| triggers_framework | |||
| triggers_framework. | string | "Parallel" | Documented only by its default. Run kcode config defaults for the full table. |
| triggers_framework. | string | "Silent" | Documented only by its default. Run kcode config defaults for the full table. |
| triggers_framework. | integer | 60 | Documented only by its default. Run kcode config defaults for the full table. |
| triggers_framework. | integer | 8 | Documented only by its default. Run kcode config defaults for the full table. |
| triggers_framework. | integer | 60 | Documented only by its default. Run kcode config defaults for the full table. |
| triggers_framework. | integer | 50 | Documented only by its default. Run kcode config defaults for the full table. |
| triggers_framework. | integer | 30 | Documented only by its default. Run kcode config defaults for the full table. |
| updater | |||
| updater. | boolean | true | Whether the app checks for a newer kcode and downloads it by itself (as it starts and every hour) so the next start uses it. A downloaded update posts one ↑ Update row in the notification center, with a desktop banner while the window isn't focused: kcode 0.6.0 is downloaded. Restart kcode to use it. A check reads the signed release index from kcode.sh's API, sending kcode's version in the user agent and nothing else; a failed one is logged, not shown. Off, kcode checks only when you ask: /upgrade, the palette's Check for updates, kcode upgrade. A debug or dev-release build doesn't check. Restart-only. |
| user_providers | |||
| user_providers. | integer | 64000 | The least context, in tokens, a model on a provider you added should get; Settings › Providers' form names each model that gets less, with the server's own setting that raises it: Ollama's Context length or OLLAMA_CONTEXT_LENGTH, LM Studio's Context Length, llama-server's --ctx-size, vLLM's --max-model-len. A model with less still runs, but kcode's system prompt and tools take much of a small window. Restart-only. |
| user_providers. | integer | 3600 | How often, in seconds, the running app asks a subscription sign-in's server which models the account has. kcode also asks at sign-in, when the providers change and after the server refuses a model. Read as at least 60. Not on the Settings page. Restart-only. |
| worktree | |||
| worktree. | boolean | true | Closing a worktree session whose checkout is clean (no uncommitted files (those git status lists, read by git's own ignore rules) and no commits past the base) deletes the checkout, its build folder, the kcode/<name> branch and the session with its conversation, which can't be resumed afterwards; a toast names what went. Dirty checkouts are always kept (fail-closed), and so is a checkout another session works in (a fork of the worktree session, or a session opened there) with a toast naming that session. kcode's own files in the checkout's .kcode folder (its database, checkouts, build folders, skill state and /share exports) never count as changes; any other change there, such as an edited rule or config, does. Set false to keep every closed worktree session resumable. Default true. The worktree's base project decides: its .kcode/config.toml is read when the session closes, while a change to your own config.toml applies after a restart. |
| worktree. | Per-project env template table: each KEY = "value" under [worktree.env] is rendered and injected into a worktree session's shell environment (the in-process shell and every command it runs: crash restarts included) and into the language servers its lsp tool starts. Values may use {{slot}} (the worktree's stable isolation slot, lowest-free ≥ 1 per project, never one a checkout still being created holds, persisted for the worktree's life), {{slug}}, {{project}} (the base directory name), {{port}} (= worktree.port_base + slot), {{domain}} (<slug>.localhost: macOS resolves *.localhost to loopback system-wide, and browsers scope cookies by host, so distinct slugs isolate browser state with no proxy), and the {{N+slot}} arithmetic form for extra port families (VITE_PORT = "{{5173+slot}}"). A bad entry is skipped with a logged warning; the rest still apply. Project scope is the natural home: each project owns its port/database conventions. kcode also always injects PORT (= {{port}}, the worktree's own port, unless an entry here names PORT), CARGO_BUILD_BUILD_DIR (<base>/.kcode/target/<slug>, the worktree's own Cargo build folder, unless an entry here names it) and the KCODE_WORKTREE_SLUG/SLOT/DOMAIN/BASE identity vars (appended last, so templates can't shadow them); a worktree:create / worktree:remove hook's {{env.KEY}} sees the same values, PORT included. Empty by default. | ||
| worktree. | integer | 3000 | Base for a worktree session's port: its PORT env var and the {{port}} template variable are port_base + slot, so the worktree in slot 1 gets 3001. The base checkout is implicitly slot 0. The base project's own value, which the worktree's shell and its worktree:create / worktree:remove hooks both use. Default 3000. |