Kode FAQ: Installation, Configuration, and Gate Failures

Answers to common questions about Kode installation, configuration, verification gates, model support, Ghost Branches, and CI/CD usage.

You’ll find quick answers here to the questions that come up most often — from choosing between kode run and kode loop, to configuring a local LLM, to understanding what happens when the TUI won’t start. If you don’t find what you need, check the audit log (logs/kode.log) and the Gate Failures guide for deeper diagnostics.

What's the difference between kode run and kode loop?

kode run generates a patch, runs it through the verification gate, and applies it to your filesystem in one shot — but it stops there. It does not execute your test suite.

kode loop does everything kode run does, and then runs your configured test command. If the tests pass, the changes are kept. If the tests fail, Kode automatically rolls back all applied changes atomically using a pre-loop snapshot, and your working tree is restored to its original state.

Use kode run when you want to review and test manually. Use kode loop when you want full automation and have a reliable test suite.

Can I use Kode with a local LLM (Ollama, LM Studio)?

Yes. Kode uses the OpenAI-compatible API format, so any local server that exposes a /v1/chat/completions endpoint will work.

Set two environment variables before running any kode command:

export KODE_LLM_ENDPOINT="http://localhost:11434/v1"   # Ollama default
export KODE_LLM_MODEL="codellama:13b"                  # or whichever model you've pulled

For LM Studio, the default endpoint is typically http://localhost:1234/v1. You do not need an API key for purely local servers, but if your server requires one, set KODE_LLM_API_KEY as well.

Run kode models to verify Kode can reach the endpoint and list available models.

How do I add a custom AI provider?

There are two ways:

Interactive setup: Run kode providers login to walk through a provider selection wizard. Kode will prompt you for the provider name, endpoint, and API key, and write the result to .kode/kode.json.

Manual configuration: Open .kode/kode.json and set the model field to the provider’s model string (e.g., "anthropic/claude-opus-4-5"). Then set the corresponding API key environment variable for that provider. Run kode models to see the full list of recognized model strings and their required environment variables.

If you want to use a provider not listed by kode models, you can point Kode at any OpenAI-compatible endpoint using KODE_LLM_ENDPOINT and KODE_LLM_MODEL.

What is the Kode Gateway?

The Kode Gateway is a built-in LLM proxy hosted at https://api.trykode.xyz. It is the default provider when you first install Kode.

The Gateway routes your requests to multiple upstream model providers — OpenAI, Anthropic, DeepSeek, Google, and OpenRouter — and handles authentication, rate limiting, and fallback on your behalf. This means you can switch models in .kode/kode.json without managing separate API keys for each provider.

If you prefer to call a provider directly (for cost, latency, or compliance reasons), set KODE_LLM_ENDPOINT to the provider’s native API URL and KODE_LLM_API_KEY to your direct API key. Kode will bypass the Gateway entirely.

Why is Kode blocking my code with a Blast Radius failure?

The Blast Radius Gate is triggered when a patch would affect more downstream files than your configured threshold. The default limit is 3 files.

Kode builds a dependency graph of your module’s imports and, before writing anything, counts how many files transitively depend on each modified file. If that count exceeds max_blast_radius, the write is blocked.

You have two options:

1. Increase the threshold for large, intentional refactors. In .kode/kode.json:

   {
     "engine": {
       "max_blast_radius": 10
     }
   }
   

2. Break the change into smaller pieces. Modify only the internal implementation without touching the exported API, then update callers in separate tasks. This is the safer approach and keeps each change reviewable.

See the Blast Radius Gate section of the Gate Failures guide for more detail.

Does Kode support Python and Rust?

Yes, both are supported.

The Syntax Gate checks Python files with bracket-balance validation that handles triple-quoted strings, comments, and continuation lines. Rust files are checked with the same bracket/brace balance logic used for TypeScript and JavaScript.

The Imports Gate validates Python imports against the standard library and local project packages. Third-party Python packages are not hard-blocked (Kode cannot reliably inspect all virtual environments), so import issues in Python produce warnings rather than hard failures.

For Rust, import validation is deferred to Cargo — the Imports Gate skips .rs files entirely on the assumption that cargo check will catch resolution errors downstream.

Go and TypeScript have the deepest static analysis support (full AST parsing for Go, node_modules resolution for TypeScript).

How does Blindfold Mode affect output quality?

Blindfold Mode obfuscates your identifiers — variable names, function names, type names — before sending code to the LLM. After the model returns a patch, Kode applies a reverse mapping to restore the original names. Your code functions identically before and after.

The trade-off is context. The LLM cannot use the semantic meaning of your names to guide its suggestions. For most coding tasks — adding a method, fixing a bug, implementing a specific algorithm — this has little effect because the model is working from structural context.

For tasks that benefit from naming intuition (e.g., “suggest a cleaner way to structure this module” or creative refactoring), Blindfold Mode may produce slightly less context-aware results. In those cases, consider disabling it for the specific task or using a system prompt that provides explicit structural guidance.

Blindfold Mode is primarily a data-privacy feature. If your codebase contains sensitive identifier names you don’t want transmitted to an external API, enable it globally in .kode/kode.json.

Can I use Kode in CI/CD without interactive prompts?

Yes. Kode is designed to run non-interactively in CI pipelines.

Set the following before invoking any Kode command:

export KODE_NO_INSTALL=1       # Suppress install/update prompts
export KODE_LLM_API_KEY="..."  # Authentication for the LLM provider

For a one-shot health analysis in CI, use:

kode daemon --once

All commands emit structured JSON when stdout is not a TTY, so you can pipe output directly to jq or a log aggregator. Use --log-dir to control where kode.log is written:

kode loop --task "fix failing tests" --log-dir /tmp/kode-logs

To store and inspect verification results across CI runs, archive logs/kode.log as a CI artifact.

Where are audit logs stored?

All verification results are appended to logs/kode.log in your project’s working directory. The file uses JSONL format — one JSON object per line.

Each entry contains:

{
  "timestamp": "2025-01-15T10:23:45.123Z",
  "task_id": "abc123",
  "status": "FAIL",
  "files": ["internal/handler/user.go"],
  "failures": { "internal/handler/user.go": "imports: Unrecognized imports: github.com/nonexistent/pkg" },
  "rounds_used": 2,
  "duration_ms": 1842,
  "model": "gpt-4o"
}

View an aggregate summary with kode stats. To change the log location, pass --log-dir <path> to any kode verify or kode loop command.

You can query the log directly with jq:

# Show all failures
jq 'select(.status == "FAIL") | .failures' logs/kode.log

# Count failures by gate type
jq -r 'select(.status == "FAIL") | .failures | to_entries[] | .value | split(":")[0]' logs/kode.log | sort | uniq -c

How do I integrate Kode with Claude Desktop?

Kode ships a built-in MCP (Model Context Protocol) server. Start it with:

kode mcp serve

Then add Kode to Claude Desktop’s configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "kode": {
      "command": "kode",
      "args": ["mcp", "serve"]
    }
  }
}

Once configured, Claude Desktop can invoke Kode’s verification and code-generation tools directly from the chat interface. See the MCP Integration guide for the full configuration, available tools, and troubleshooting tips.

What happens if tests fail during kode loop?

Kode takes a filesystem snapshot of your working tree before the loop begins. If the test command exits with a non-zero status, Kode:

1. Marks the loop run as failed
2. Atomically rolls back all files it modified to their pre-loop state using the snapshot
3. Reports which test(s) failed and what the test output was

Your working tree is fully restored — no partial changes are left on disk. The failure is recorded in logs/kode.log with the test output attached.

To retry, fix the underlying issue (either by adjusting your prompt or by modifying configuration) and run kode loop again. Kode will start fresh from the current file state.

How do I update Kode to the latest version?

Run the built-in upgrade command:

kode upgrade

To upgrade to a specific version, pass the version as a positional argument:

kode upgrade v1.4.2

If you installed Kode via npm, use npm to update instead:

npm install -g @sicario-labs/kode

After upgrading, run kode --version to confirm the new version is active. If you have the TUI bundle cached locally (in KODE_TUI_DIR), delete it to force a re-download of the matching TUI version.

The TUI won't start — what do I do?

The Kode TUI is shipped as a separate bundle (approximately 52 MB) downloaded from GitHub Releases on first launch. If the download fails or the TUI exits immediately, try the following:

Check your internet connection. The download requires access to github.com. If you’re behind a proxy, configure it with standard HTTP_PROXY / HTTPS_PROXY environment variables.

Override the bundle URL. If GitHub Releases is blocked or slow in your region, set an alternative:

export KODE_TUI_BUNDLE_URL="https://your-mirror.example.com/kode-tui-v1.4.0.tar.gz"
kode tui

Use a pre-downloaded bundle. Download the bundle manually, extract it, and point Kode at the directory:

export KODE_TUI_DIR="/path/to/extracted/tui-bundle"
kode tui

Check for version mismatch. If you recently ran kode upgrade, the cached TUI bundle may be incompatible. Delete the bundle directory (default: ~/.kode/tui/) and let Kode re-download it.

All other kode commands (run, loop, verify, stats, explain) work fully without the TUI.

Can I use Kode on Windows?

Yes. Install Kode on Windows using the PowerShell install script:

irm https://raw.githubusercontent.com/sicario-labs/kode/master/script/install.ps1 | iex

Alternatively, install via npm (works on any platform with Node.js installed):

npm install -g @sicario-labs/kode

After installation, open a new PowerShell or Command Prompt window and run kode --version to confirm. All commands and flags work the same on Windows. File paths in configuration and prompts should use forward slashes or escaped backslashes.