Settings Reference

This reference lists user-configurable settings, their types, defaults, and purposes. Project settings override agent-directory settings. Resource lists are combined. See Configuration for file locations and trust behavior.

Add "$schema": "https://knightcode.dev/schemas/settings.schema.json" to settings.json for editor validation and completion.

Model and thinking

Cache warming runs only when the model declares a cache lifetime and KnightCode estimates at least $0.05 in avoided cache-miss cost. Refresh usage counts toward session totals but does not enter model context. /session shows the next decision; extensions can override it with cache_warming_decision. See Prompt Cache Lifetimes.

See Choose a Model for model selection and thinking controls.

Interaction

Tools

Available built-in tools are read, bash, powershell, edit, write, grep, find, and ls. defaultTools can also name codemode and tool_search, which built-in extensions register inactive, and other extension tools registered inactive.

A list of only +name and -name entries changes the inherited selection instead of replacing it. For example, this enables codemode next to the default tools:

{
  "defaultTools": ["+codemode"]
}

This replaces bash with powershell and enables grep: ["-bash", "+powershell", "+grep"]. Project settings apply on top of user settings: a project list with only +name and -name entries changes the user's selection, and a project list with a plain name replaces it. In one list, plain names form the selection, and +name and -name then apply in order.

/reload enables tools newly added to defaultTools. It does not disable tools removed from it or re-enable unchanged tools you turned off. --tools with plain names, --no-tools, and --no-builtin-tools override defaultTools, also on reload.

CLI tool options override this setting for one invocation. --tools with only +name and -name entries changes the resolved defaultTools selection instead, for example knightcode --tools +codemode. On /reload, these entries apply to the reloaded setting too, so a tool removed with -name stays removed. See Command Line.

The web tools webfetch and websearch and the question tool ask_user are not part of the default defaultTools. /tools turns them on for the current session, which writes nothing to disk, or on or off by default, which is saved in ~/.knightcode/agent/tools.json together with the websearch provider and Brave key. Naming one in defaultTools also turns it on, unless /tools has it off.

Sessions and context

Compaction

Compaction token values must be non-negative safe integers. Each value resolves independently from the matching model override, then the ordinary compaction setting, then the built-in default. Project and user objects merge before model lookup.

See Compaction Reference for trigger, summarization, and validation behavior.

Branch summaries

Terminal and display

See Themes and Terminal Setup for format and platform details.

Worktrees

Worktree settings belong to the user: they are read from the agent-directory settings file only, never from a project's.

Environments

A project's environments live in .knightcode/environments.json, which can be committed:

{
  "version": 1,
  "environments": [
    {
      "name": "node",
      "setup": { "default": "cd \"$KNIGHTCODE_WORKTREE_PATH\" && npm ci" },
      "cleanup": { "default": "rm -rf \"$KNIGHTCODE_WORKTREE_PATH/.cache\"" },
      "actions": [{ "name": "Test", "command": { "default": "npm test" } }]
    }
  ]
}

Each script has default, macos, linux and windows variants; the platform's wins. Scripts run in bash on every platform (Git Bash on Windows, or the shellPath setting), so one default usually covers all three; a platform variant is for a command that differs. The setup script runs when a worktree is created and the cleanup script before one is deleted, both at the project root, with KNIGHTCODE_SOURCE_TREE_PATH (the checkout the worktree came from) and KNIGHTCODE_WORKTREE_PATH (the worktree) set. Since they start in the main checkout, work on the worktree through KNIGHTCODE_WORKTREE_PATH, as the example does: a bare npm ci would install into the main checkout. A failing setup keeps the worktree and marks it setupFailed; a failing cleanup is a warning. An untrusted project's scripts never run. actions are for the desktop app's toolbar.

.worktreeinclude

Ignored files are not copied into a new worktree unless the repository root's .worktreeinclude (gitignore syntax) lists them, such as .env. A file is copied only if the worktree ignores it too, so it can never be committed or handed off by accident, and nothing is created through a symlink or junction.

Network and retries

Keep retry.provider.maxRetries at 0 unless provider-level retries are required. Provider retries can delay KnightCode from handling quota and usage-limit errors itself.

Shell

See Shell aliases for shell setup and KnightCode Packages for package-manager behavior.

Resources

Resource paths in user settings resolve from the agent directory. Paths in project settings resolve from the project .knightcode directory. Absolute paths and ~ are supported.

Resource arrays support glob exclusions with !pattern, exact inclusion with +path, and exact exclusion with -path. KnightCode loads resources listed in both user-level and project settings.

The built-in extensions are named builtin:mcp, builtin:llama.cpp, builtin:codemode, and builtin:tool-search in extensions. They load by default; -builtin:mcp disables one. A +builtin:<name> or -builtin:<name> entry in project settings overrides the user setting. knightcode config lists them under Built-in. --no-extensions disables them too, and -e builtin:<name> loads one explicitly.

Updates, telemetry, and warnings

Disable automatic updates

Automatic updates are on by default. Open /settings, search for Automatic updates, and change it from true to false. KnightCode saves the preference in your user-level settings.json; no restart or /reload is needed. It applies to subsequent update checks and does not cancel a download already running. Change it back to true in /settings to re-enable automatic updates.

Alternatively, add "autoUpdate": false to your user-level settings.json:

• Windows: %USERPROFILE%\.knightcode\agent\settings.json
• macOS / Linux: ~/.knightcode/agent/settings.json

{
  "autoUpdate": false
}

Create the file if it does not exist; otherwise add this property to the existing JSON object, keeping your other settings. If KNIGHTCODE_CODING_AGENT_DIR overrides the agent directory, use settings.json in that directory instead. Project-local .knightcode/settings.json cannot override this preference.

KnightCode still checks for new versions and shows update notices, but does not download or install updates automatically. Run knightcode update whenever you want to update manually. Set autoUpdate to true, or remove it, to restore automatic updates.

After manually editing the file, restart KnightCode or run /reload. The new preference applies to subsequent update checks; it does not cancel a download already running.

Environment variables are optional alternatives, set in the shell or operating system environment before launching KnightCode, not inside settings.json:

• KNIGHTCODE_DISABLE_AUTO_UPDATE=1 disables automatic downloads even when autoUpdate is true. Unset the variable to let the setting control downloads again. The updater treats any non-empty value as disabling, including 0.
• KNIGHTCODE_SKIP_VERSION_CHECK=1 disables both automatic checks and downloads.

Neither variable blocks explicit knightcode update. Offline, print, JSON, and RPC sessions never start background updates. See Command Line for update behavior and Environment Variables for shell examples.