Configuration

Configure Kitten without guessing.

Start with a small JSON delta, then add providers, sessions, preferences, and local MCP servers when you need them.

File location and validation

Config is optional. Kitten first checks KITTEN_CONFIG, then$XDG_CONFIG_HOME/kitten/config.json, then~/.config/kitten/config.json.

Every field is a delta over Kitten's defaults. Existing files are strict JSON: unknown keys, malformed JSON, and invalid values stop startup instead of falling back silently.

Choose the sessions Kitten opens

With no sessions array, Kitten seeds one session for each configured provider in the directory where you launch it. Add an array when you need a specific order, title, task, or working directory.

{
  "theme": "dark",
  "sessions": [
    { "provider": "codex", "cwd": ".", "title": "Implementation" },
    { "provider": "claude-code", "cwd": ".", "title": "Review" },
    { "provider": "cursor", "cwd": ".", "title": "Explore" }
  ]
}

provider: One of claude-code, codex, or cursor.
cwd: Required. Relative paths resolve from the directory where you launch Kitten and must exist.
title: Optional. The directory name is used when it is omitted.
task: Optional initial task text for the session.

Override a provider or set model defaults

Provider overrides merge by field, so changing one command, argument list, display name, or environment value leaves the rest of the recipe in place. The deprecatedagents alias still loads, but use providers for new files.

Kitten currently recognizes Claude Code, Codex, and Cursor. More Agent Client Protocol (ACP) connections are planned, but a config file cannot invent an unsupported provider key.

{
  "providers": {
    "codex": {
      "displayName": "Codex implementation",
      "env": {
        "INITIAL_AGENT_MODE": "agent-full-access"
      }
    }
  },
  "providerDefaults": {
    "codex": { "model": "gpt-5.4", "effort": "high" },
    "claude-code": { "model": "claude-opus-4-1", "effort": "high" }
  }
}

providerDefaults accepts only model and effort. They are personal preferences, not a command to change a running session. Kitten applies them through the intentional provider-selection flow and never writes a manual live choice back into this block.

Set cockpit preferences

theme: auto, light, dark, catppuccin-mocha, or catppuccin-latte.
welcomeBanner: auto, always, or off.
clarificationTimeoutSeconds: An integer from 1 to 3600. The default is 300 seconds.
persistenceEnabled: Controls local session persistence. It is on by default.
telemetryEnabled: Opt in to local, content-free JSONL counters. It is off by default.
transcriptWindowingEnabled: Opt in to the bounded transcript presentation experiment. It is off by default.
statusline: Requires llmDisclosureAcknowledged; separator and line must be supplied together.

Add local MCP servers and editor tools

mcpServers is a name-keyed map of stdio commands. Remote HTTP and SSE transports are rejected. Kitten already adds its own kitten-ask-userserver; do not add that server to this map.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Set each referenced environment variable before starting Kitten. If a variable cannot be resolved, Kitten skips that declared server and shows a warning.

{
  "editor": {
    "kind": "custom",
    "executable": "code",
    "args": ["--goto", "{file}"]
  },
  "shell": {
    "enabled": true,
    "scrollback": 5000
  }
}

A custom editor's args must include exactly one complete{file} placeholder. Shell scrollback accepts an integer from 0 through 100000.

Know what changes immediately

Kitten watches a valid config file. While the cockpit is open, it updates the theme, statusline, and provider-default snapshot. Change providers, sessions, MCP servers, shell settings, persistence, telemetry, or transcript windowing before the next launch.

A file that exists but cannot be read or validated is a configuration error. Fix the named field and restart; Kitten does not quietly replace a broken file with defaults.