Skip to main content

Documentation Index

Fetch the complete documentation index at: https://kode-f177b001.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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
  },
  "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 detectedDefault command
go.modgo test ./...
package.jsonnpm test
Cargo.tomlcargo test
pyproject.toml / requirements.txtpytest
Gemfilebundle 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.

​
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.

Providers

Configure AI providers, API keys, and model strings.

Environment Variables

Override config values at runtime using environment variables.