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.

Every Kode task follows the same spine: build a surgical context graph, generate structured JSON hunks via an LLM, pass each hunk through a chain of verification gates, and write only what passes. By the end of this guide you will have initialized a project, run your first task, and read the verification stats that prove what changed — and why.

​
Prerequisites

  • Kode installed and available on your PATH (kode --version should print a version string)
  • A code project inside a git repository (Kode reads and writes files relative to the repo root)
  • Your API key exported as KODE_LLM_API_KEY or OPENAI_API_KEY
export KODE_LLM_API_KEY="sk-..."

​
Steps

1
Initialize your project
2
Run kode init from the root of your repository. Kode creates a .kode/ directory and writes a default kode.json configuration file. It also auto-detects your test command and, if the optional security engine is available, installs it as an extra verification gate.
3
kode init
4
Example output:
5
── Kode Init ───────────────────────────────────────
✓ Created directory /your/project/.kode
  Auto-detected test command: go test ./...
✓ Written /your/project/.kode/kode.json

── Engine Features ──────────────────────────────────
  TDD Mode:        ON  (writes blocked unless test file present)
  Test Command:    go test ./...
  Blast Radius:    3 files max per verify round
  Token Budget:    $1.50 per loop cycle
  Blindfold:       OFF (identifier obfuscation before LLM send)
6
If Kode finds a .env file in the project root it will template the gateway URL as ${KODE_GATEWAY_URL} so you can rotate endpoints without editing the config file.
7
Review .kode/kode.json
8
Open .kode/kode.json to familiarise yourself with the defaults before running any task:
9
{
  "$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.50,
    "blindfold_mode": false
  },
  "providers": {
    "primary": "kode",
    "gateway_url": "https://api.trykode.xyz"
  }
}
10
Key settings to understand before your first task:
11
SettingDefaultWhat it controlsengine.tdd_modetrueBlocks writes to production files unless a corresponding test file already existsengine.max_blast_radius3Hard limit on the number of files a single verify round may touchengine.token_budget_usd1.50Cost cap per loop cycle — Kode aborts before exceeding thisengine.blindfold_modefalseWhen true, obfuscates identifier names before sending code to the LLM
12
Run your first task
13
Pass a natural-language description of the change you want to kode run:
14
kode run "add input validation to the user registration handler"
15
Behind the scenes Kode executes four stages:
16
  • Plan — Kode walks your codebase with Tree-sitter, building an AST-based context graph capped at 8 000 tokens. Only the files, functions, and import edges relevant to your task description are included.
  • Generate — The context graph is serialised into a prompt and sent to the configured LLM. The model returns structured JSON hunks (not raw diff text) describing each change.
  • Verify — Every hunk passes through the verification gate before anything is written to disk. The gate runs checks in sequence: syntax, imports, calls, architecture rules, and diff applicability.
  • Apply — Hunks that pass all gates are written atomically. Hunks that fail are logged with the name of the failing check but never written.
    • 17
    Example output:
    18
    ── Generating patches ───────────────────────────────
  Task: add input validation to the user registration handler
  LLM: anthropic/claude-sonnet-4-6
✓ Generated (3.2s): 4 hunk(s)

── Verifying patches ────────────────────────────────
✓ Applied 4 hunk(s) (4.1s)

✓ All done (4.1s)
    19
    Check verification stats
    20
    After one or more runs, inspect the aggregate verification metrics:
    21
    kode stats
    22
      ┌─ Kode Gatekeeper Statistics ──────────────────────────────────────────┐
  │
  │  Total Verifications:  12
  │  Passed:               10  (83.3%)
  │  Failed:               2   (16.7%)
  │  Avg Duration:         312.4ms  (total: 3.7s)
  │
  │  Failure Breakdown (2 total):
  │    imports:      1  (50.0%)
  │    calls:        1  (50.0%)
  │
  │  Most Failed Files (top 10):
  │    internal/auth/handler.go                       2 failures
  │
  │  Models Used:
  │    anthropic/claude-sonnet-4-6:  12  (100.0%)
  │
  │  Daily Trend (last 14 days):
  │    2025-07-01 ████████████████░░░░ 8/10 (80%)
  │    2025-07-02 ████████████████████ 2/2 (100%)
  │
  │  Recent Verdicts (last 20):
  │    ✓ ✓ ✗ ✓ ✓ ✓ ✓ ✓ ✗ ✓ ✓ ✓
  │
  └────────────────────────────────────────────────────────────────────────┘
    23
    The output shows the overall pass rate, a breakdown of failures by gate name, the top-failing files (useful when a file repeatedly triggers the same gate), model usage, a daily trend bar chart, and the most recent verification verdicts.

    ​
    Understanding gate failures

    When a hunk fails verification, the log entry records the gate name and a short message. Use kode explain <check> to get a full description of that gate, its common causes, and suggested fixes: 
    kode explain syntax
    Each explain command also prints up to five recent examples pulled from logs/kode.log so you can see which files triggered the gate in your own project.
    If the same gate fails repeatedly for a specific file, inspect it with kode plan --graph "<task>" to see the full dependency graph for that area of the codebase. Understanding what the context graph captures (and what it omits) often reveals why the LLM is generating incorrect hunks.
    kode run is a shortcut for kode generate --apply. It generates patches and immediately applies verified ones, but it does not run your test suite after applying. Use kode loop when you want the full Plan → Generate → Verify → Apply → Test pipeline with automatic rollback on test failure.

    ​
    Next steps

    Loop Mode

    Run the full pipeline with test execution and automatic rollback — including Ghost Branch parallel strategies.

    Verify CLI

    Run the verification gate directly against a JSON hunk file or a set of proposed file contents.