> ## 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.
# 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`
```bash theme={null}
export KODE_LLM_API_KEY="sk-..."
```
## Steps
### Initialize your project
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.
```bash theme={null}
kode init
```
Example output:
```
── 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)
```
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.
### Review `.kode/kode.json`
Open `.kode/kode.json` to familiarise yourself with the defaults before running any task:
```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.50,
"blindfold_mode": false
},
"providers": {
"primary": "kode",
"gateway_url": "https://api.trykode.xyz"
}
}
```
Key settings to understand before your first task:
| Setting | Default | What it controls |
| ------------------------- | ------- | --------------------------------------------------------------------------------- |
| `engine.tdd_mode` | `true` | Blocks writes to production files unless a corresponding test file already exists |
| `engine.max_blast_radius` | `3` | Hard limit on the number of files a single verify round may touch |
| `engine.token_budget_usd` | `1.50` | Cost cap per loop cycle — Kode aborts before exceeding this |
| `engine.blindfold_mode` | `false` | When `true`, obfuscates identifier names before sending code to the LLM |
### Run your first task
Pass a natural-language description of the change you want to `kode run`:
```bash theme={null}
kode run "add input validation to the user registration handler"
```
Behind the scenes Kode executes four stages:
1. **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.
2. **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.
3. **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.
4. **Apply** — Hunks that pass all gates are written atomically. Hunks that fail are logged with the name of the failing check but never written.
Example output:
```
── 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)
```
### Check verification stats
After one or more runs, inspect the aggregate verification metrics:
```bash theme={null}
kode stats
```
```
┌─ 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):
│ ✓ ✓ ✗ ✓ ✓ ✓ ✓ ✓ ✗ ✓ ✓ ✓
│
└────────────────────────────────────────────────────────────────────────┘
```
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 ` to get a full description of that gate, its common causes, and suggested fixes:
```bash Syntax failures theme={null}
kode explain syntax
```
```bash Import failures theme={null}
kode explain imports
```
```bash Call-signature failures theme={null}
kode explain calls
```
```bash Architecture violations theme={null}
kode explain architecture
```
```bash Diff application failures theme={null}
kode explain diff_applier
```
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 ""` 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
Run the full pipeline with test execution and automatic rollback — including Ghost Branch parallel strategies.
Run the verification gate directly against a JSON hunk file or a set of proposed file contents.