Introduction

KODA reads your project, edits files and runs commands, always asking for approval on sensitive actions. It works with several LLM providers and is compatible with the OpenCode structure for agents, skills and commands.

Every provider past the first three is OpenAI-compatible and served from the catalog with no extra dependency. Each uses <NAME>_API_KEY, <NAME>_MODEL and <NAME>_BASE_URL; connect with /connect and select with KODA_PROVIDER=<name>. Local servers (ollama, lmstudio, vllm, llamacpp) need no key.

Installation

Requires Node >= 22.

npm install -g @koda-tools/koda

Then just open a terminal in your project and run:

koda

To try it without installing, use npx @koda-tools/koda.

UPDATE

npm update -g @koda-tools/koda

Configuration

Provider and model are set through environment variables.

# choose the provider (default: openai)
export KODA_PROVIDER=anthropic
export ANTHROPIC_API_KEY=sk-...
export ANTHROPIC_MODEL=claude-sonnet-4-6

Each <NAME>_BASE_URL overrides the default shown above. Hosted providers require their key; local servers do not.

CONNECT A PROVIDER (/CONNECT)

Instead of exporting variables, save the key with /connect inside KODA, or with koda connect straight from the terminal (requires an interactive terminal).

# pick the provider from a list (↑/↓, Enter, Esc cancels)
/connect

# or pass the provider directly
/connect anthropic
koda connect anthropic

Available providers: openai, anthropic and gemini. Ollama is local and needs no key. The list shows the state of each one: connected, from environment or not connected.

After choosing, type the key (the input is hidden). It is saved to ~/.config/koda/auth.json with permission 600.

OLLAMA (LOCAL)

export KODA_PROVIDER=ollama
export OLLAMA_BASE_URL=http://127.0.0.1:11434/v1
export OLLAMA_TOOL_SUPPORT=true

Commands

Type / at the prompt to see suggestions.

Use @agent task to delegate to a subagent.

START A PROJECT (INIT)

Run koda init in the project root, or /init inside a session, to create the folders KODA reads its extensions from. It needs no API key and no interactive terminal.

# from the terminal
koda init

# or inside KODA
/init

Created  .koda/commands
Created  .koda/skills
Created  .koda/agents

Agents

Tools

MCP servers

KODA connects to MCP servers using the same mcp section as OpenCode, in koda.json or opencode.json (project root, .koda/, .opencode/ or the global ~/.config/koda).

{
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "."],
      "environment": { "LOG_LEVEL": "info" }
    },
    "docs": {
      "type": "remote",
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer {env:DOCS_TOKEN}" }
    },
    "old-server": { "enabled": false }
  }
}

{env:NAME} in any value is replaced by that environment variable. Each tool is exposed as <server>_<tool>, and /mcp shows each server's status and tool count. A server that fails never blocks the session.

Local servers only receive a safe set of variables (PATH, HOME...) plus the environment you list, never your API keys.

PERMISSIONS

MCP calls are allowed by default. Use the mcp key to restrict them; patterns match the tool name.

permission:
  mcp:
    "*": allow
    "docs_*": ask
    "filesystem_write_file": deny

Custom commands

Create a Markdown file in .koda/commands/ (run koda init to create the folder). The file name becomes the command.

# .koda/commands/review.md
---
description: Reviews a file
agent: plan
model: openai/gpt-4.1-mini
subagent: false
---
Review the file $1 focusing on $2.
Full arguments: $ARGUMENTS

Usage: /review src/index.ts security

Custom agents

Defined in Markdown (body = prompt) or JSON, in the same directories as commands.

---
description: Security reviewer
mode: subagent
model: anthropic/claude-sonnet-4-6
temperature: 0.1
steps: 15
permission:
  edit: deny
  bash: ask
---
You review code looking for vulnerabilities.

Skills

Each skill is a folder with a SKILL.md.

.koda/skills/<name>/SKILL.md

The .opencode, .claude and .agents folders are also read. List them with /skills.

Permissions

Each action resolves to allow, ask or deny. With glob patterns, the last matching rule wins.

permission:
  read: allow
  edit: ask
  bash:
    "*": ask
    "git status": allow
    "rm *": deny

Keys: read, edit, list, glob, grep, bash, task, skill, mcp.

Use as a library

The SDK is its own package, @koda-tools/core, with no terminal dependencies, so it is light to install and safe to bundle in other hosts such as an editor extension. @koda-tools/koda re-exports everything from it, so existing imports keep working.

npm install @koda-tools/core

import { bootstrapKoda, loadConnection } from "@koda-tools/core";

const connection = await loadConnection({ env: process.env });
const koda = await bootstrapKoda({
  cwd: process.cwd(),
  connection,
  policies: { approve: async (title) => askUser(title) },
});
await koda.close();

Approvals are supplied by the host, as an object or as a function run once the provider is built (a missing API key fails before it is called). The terminal UI (runInteractive, renderHeader) is a separate export:

import { runInteractive } from "@koda-tools/koda/tui";