Run Your First Task with Kode

Walk through running your first AI-generated code task with Kode, from project initialization to seeing a verified patch applied to your codebase.

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

Syntax failures

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.