> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trykode.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```json .kode/kode.json theme={null}
{
  "$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

<ParamField body="model" default="anthropic/claude-sonnet-4-6" type="string">
  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](/configuration/providers) for the full list of supported model strings.
</ParamField>

<ParamField body="small_model" default="anthropic/claude-haiku-4-5" type="string">
  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.
</ParamField>

### Prompt customization

<ParamField body="instructions" default="[&#x22;AGENTS.md&#x22;]" type="string[]">
  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.
</ParamField>

### Permissions

<ParamField body="permission.edit" default="ask" type="string">
  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.
</ParamField>

<ParamField body="permission.bash" default="ask" type="string">
  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.
</ParamField>

### Engine settings

<ParamField body="engine.tdd_mode" default="true" type="boolean">
  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.
</ParamField>

<ParamField body="engine.test_command" default="auto-detected" type="string">
  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.
</ParamField>

<ParamField body="engine.max_blast_radius" default="3" type="integer">
  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.
</ParamField>

<ParamField body="engine.token_budget_usd" default="1.50" type="number">
  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.
</ParamField>

<ParamField body="engine.blindfold_mode" default="false" type="boolean">
  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](/concepts/blindfold-mode) for details.
</ParamField>

<ParamField body="engine.architecture_rules.disallowed_imports" default="{}" type="object">
  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.

  ```json theme={null}
  "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.
</ParamField>

### Provider settings

<ParamField body="providers.primary" default="kode" type="string">
  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.
</ParamField>

<ParamField body="providers.gateway_url" default="https://api.trykode.xyz" type="string">
  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.
</ParamField>

### Skills & MCP

<ParamField body="skills.paths" default="[]" type="string[]">
  A list of paths to skill files — reusable task templates Kode can load when executing commands. Paths are resolved relative to your project root.
</ParamField>

<ParamField body="mcp" default="{}" type="object">
  MCP server configuration. Each key is a server name and each value is an MCP server descriptor. See [MCP Integration](/guides/mcp-integration) for the full schema and examples.
</ParamField>

## 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:

```bash theme={null}
KODE_DIR=/path/to/custom/kode kode run "add logging"
```

<Note>
  `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.
</Note>

## Related

<CardGroup cols={2}>
  <Card title="Providers" href="/configuration/providers">
    Configure AI providers, API keys, and model strings.
  </Card>

  <Card title="Environment Variables" href="/configuration/environment-variables">
    Override config values at runtime using environment variables.
  </Card>
</CardGroup>