Kode Config Format

draft

Kode Config Format

This spec defines the on-disk format and hierarchical resolution of the kode CLITUI configuration. It elevates `internalconfig/ to parity with Claude Code (settings.json`) without breaking existing YAML installs.

File location and format

Kode persists config as YAML for backwards compatibility with shipped installs. JSON inputs are also accepted (auto-detected by the leading non-whitespace byte: { or [ → JSON; otherwise YAML). Writes always emit YAML.

Scope Path Auto-created
User defaults ~/.config/kode/config.yaml Yes (on first run)
Workspace overlay <work_dir>/.kode/config.yaml No
CLI flags --once, --json, --model … n/a

Older docs may refer to ~/.kode/kode.json; that path is *ot*the canonical location — the XDG-compliant ~/.config/kode/config.yaml is authoritative. A future major version may switch to JSON; until then the extension is implementation detail.

Resolution order (last wins)

  1. Built-in defaults — see cfg := &Config{...} in internal/config/config.go.
  2. User config (~/.config/kode/config.yaml).
  3. Workspace overlay (<work_dir>/.kode/config.yaml) — merged deeply, last

    key wins.

  4. Environment variables — KODE_RELAY_URL and similar prefixed

    KODE_<UPPER_SNAKE> overrides.

  5. CLI flags — --once, --json, --model, etc.

Every key reports its origin via kode --once /config show. Surfaces must not invent additional layers; new sources go into this list with an RFC.

Schema (v1)

# Versioned schema marker (planned for v2 migrations; absent = v1).
kodeVersion: 1

# Relay endpoint. Override via KODE_RELAY_URL.
relay_url: wss://kode.koder.dev/v1/relay/ws

# Default model the agent picks when no /model is set in the session.
default_provider: claude
default_model: claude-opus-4-7

# Working directory for context engines (Chronicle, Watch, etc.).
work_dir: ~/dev

# Custom prompt prepended to every session as system instructions.
custom_instructions: ""

# Tools the agent may call. Permissions (allow/deny per glob) are a
# follow-up — see DKODE-043 §Permissões.
allowed_tools:
  - shell
  - read_file
  - write_file
  - list_dir
  - install_pkg
  - env_info

# Ambient context engines (DKODE-080 family).
context:
  git_snapshot: true
  shell_history: true
  file_watcher: true
  stderr_buffer: true
  auto_kode_md: true
  chronicle:
    enabled: false
    mode: local           # "local" or "cloud"
    interval_turns: 5

# Auto-execution post-edit (opt-in; off by default in fresh installs).
auto_lint: false
lint_cmd: ""
auto_test: false
test_cmd: ""
auto_commit: false

# Watch mode: monitor work_dir for `// kode:` and `# kode:` comments.
watch_mode: false

# Reasoning controls.
thinking_tokens: 0          # 0 = disabled
reasoning_effort: ""        # "low" | "medium" | "high"

# Other toggles.
cache_prompts: false
dry_run: false
tui_skin: kode              # "kode" | "claude" | "gemini" | "codex"
welcomed_skins: []
output_style: ""            # "" | "concise" | "explanatory" | "markdown"
yolo_mode: false            # auto-approve every tool call (UNSAFE)

Planned schema additions (DKODE-043 §Permissões / §Auth / §Hooks)

These three blocks are documented now so workspace overlays can opt in ahead of full enforcement, but the runtime ignores unknown keys until the follow-up tickets land.

agents (named agent profiles)

agents:
  - name: refactor-bot
    model: claude/claude-opus-4-7
    system_prompt: "Senior Go engineer. Prefer hyperscale-first."
    tools: [shell, read_file, write_file]
    requires:
      - tools.has: shell
      - workspace.has: go.mod

permissions (allow/deny per glob)

permissions:
  allow:
    - "fs:read:~/dev

Source: ../home/koder/dev/koder/meta/docs/stack/specs/kode/config-format.kmd