kode.json Configuration Reference for Kode Projects

The .kode/kode.json file controls Kode’s model selection, verification engine settings, token budgets, and provider configuration. Created by kode init.

The .kode/kode.json file is Kode’s project-level configuration file. Running kode init in your project root creates a .kode/ directory and writes a fully-populated kode.json inside it. Every field has a sensible default — you only need to edit what you want to change. Kode auto-detects your language ecosystem and pre-fills engine.test_command accordingly (Go, Node, Rust, Python, Ruby, and others are all recognized).

Default configuration

This is the exact file kode init generates for a Go project:

.kode/kode.json

{
  "$schema": "https://trykode.xyz/config.json",
  "version": "3.0.0",
  "model": "anthropic/claude-sonnet-4-6",
  "small_model": "anthropic/claude-haiku-4-5",
  "instructions": ["AGENTS.md"],
  "permission": {
    "edit": "ask",
    "bash": "ask"
  },
  "engine": {
    "tdd_mode": true,
    "test_command": "go test ./...",
    "max_blast_radius": 3,
    "token_budget_usd": 1.5,
    "blindfold_mode": false,
    "architecture_rules": {
      "disallowed_imports": {
        "internal/db": ["internal/gateway", "internal/daemon"]
      }
    }
  },
  "providers": {
    "primary": "kode",
    "gateway_url": "https://api.trykode.xyz"
  }
}

Field reference

Model selection

model · string · default: "anthropic/claude-sonnet-4-6"

The primary LLM used for code generation and planning. Specify models in provider/model format. Examples: anthropic/claude-sonnet-4-6, openai/gpt-4o, google/gemini-2.0-flash. See Providers for the full list of supported model strings.

small_model · string · default: "anthropic/claude-haiku-4-5"

A smaller, faster model used for critique passes and lightweight tasks like summarization and coherence checks. Keeping this separate from model lets you use a cheaper model for the high-frequency, lower-stakes reasoning steps without sacrificing the quality of the main generation pass.

Prompt customization

instructions · string[] · default: "[\"AGENTS.md\"]"

A list of file paths whose contents are prepended to every prompt Kode sends to the LLM. Use this to encode project-specific conventions, banned patterns, or architecture rules. Paths are resolved relative to your project root. If a listed file does not exist, Kode skips it silently.

Permissions

permission.edit · string · default: "ask"

Controls whether Kode can write to files. Accepted values:

• ask — Kode prompts you before applying any file change (default).
• always — Kode applies edits without asking. Use in headless or CI environments.
• deny — Kode never writes to disk; patches are shown but not applied.

permission.bash · string · default: "ask"

Controls whether Kode can execute shell commands. Accepted values:

• ask — Kode prompts you before running any command (default).
• always — Kode runs commands without confirmation.
• deny — Kode blocks all shell execution; the test runner step is skipped.

Engine settings

engine.tdd_mode · boolean · default: "true"

When true, Kode refuses to write to a production file unless a corresponding test file already exists in the repository. This is a fail-closed gate: the patch is blocked entirely, not deferred. Set to false to allow writes to production code without a test file present.

engine.test_command · string · default: "auto-detected"

The command Kode runs after applying a patch to verify correctness. Kode auto-detects this from your project root when you run kode init:

File detected	Default command
go.mod	go test ./...
package.json	npm test
Cargo.toml	cargo test
pyproject.toml / requirements.txt	pytest
Gemfile	bundle exec rspec

Override it here if your project uses a custom test runner or needs extra flags.

engine.max_blast_radius · integer · default: "3"

The maximum number of downstream files a single patch may affect in one verify round. If Kode’s blast-radius analysis determines that applying a change would touch more files than this limit, the patch is rejected before it reaches disk. Lower values enforce tighter, more surgical changes; higher values allow broader refactors.

engine.token_budget_usd · number · default: "1.50"

A cost cap (in USD) applied per loop cycle. Once Kode estimates that the accumulated token spend for the current cycle would exceed this value, it halts and reports the budget breach rather than continuing. This prevents runaway spending on open-ended tasks.

engine.blindfold_mode · boolean · default: "false"

When true, Kode SHA-256 obfuscates identifiers — variable names, function names, type names — before sending code to the LLM. The mapping is reversed locally before applying any patch, so the LLM never sees your real symbol names. Useful for proprietary codebases where leaking identifier semantics is a concern. See Blindfold Mode for details.

engine.architecture_rules.disallowed_imports · object · default: "{}"

A map of source-package globs to lists of import paths they are forbidden from referencing. Powers Gate 5 — Architecture. When a generated patch tries to import a banned path from a restricted package, the gate hard-blocks the write.

"architecture_rules": {
  "disallowed_imports": {
    "internal/db": ["internal/gateway", "internal/daemon"]
  }
}

In this example, anything inside internal/db is forbidden from importing internal/gateway or internal/daemon — preventing data-layer code from reaching into the gateway or daemon layers.

Provider settings

providers.primary · string · default: "kode"

The ID of the primary provider Kode routes requests through. Use "kode" to route through the Kode Gateway at api.trykode.xyz, which gives you unified access to all supported models under a single API key. Set this to a provider ID (e.g. "openai", "anthropic") when connecting directly to a provider without the gateway.

providers.gateway_url · string · default: "https://api.trykode.xyz"

The base URL of the Kode Gateway. You only need to change this if you are self-hosting the gateway or pointing at a staging environment. When kode init detects a .env file in your project root, it templates this value as ${KODE_GATEWAY_URL} so you can override it at runtime without modifying the committed config.

Skills & MCP

skills.paths · string[] · default: "[]"

A list of paths to skill files — reusable task templates Kode can load when executing commands. Paths are resolved relative to your project root.

mcp · object · default: "{}"

MCP server configuration. Each key is a server name and each value is an MCP server descriptor. See MCP Integration for the full schema and examples.

Config file location

By default Kode looks for .kode/kode.json relative to your current working directory. Override the config directory path with the KODE_DIR environment variable:

KODE_DIR=/path/to/custom/kode kode run "add logging"

KODE_DIR changes the directory Kode reads kode.json from and also where it installs the Sicario SAST binary. Set it to a shared path if you want multiple projects to use the same Sicario installation.

Related

Providers

Configure AI providers, API keys, and model strings.

Environment Variables

Override config values at runtime using environment variables.