KODA

A secure coding agent for the terminal, written in TypeScript. CLI and SDK.

$ koda _

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.

PROVIDER	DEFAULT MODEL
openai	gpt-4o-mini
anthropic	claude-3-5-sonnet-latest
gemini	gemini-2.5-flash
ollama	llama3.2 (local)

Installation

Requires Node >= 20.

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-3-5-sonnet-latest

PROVIDER	KEY	MODEL
openai	OPENAI_API_KEY	OPENAI_MODEL
anthropic	ANTHROPIC_API_KEY	ANTHROPIC_MODEL
gemini	GEMINI_API_KEY	GEMINI_MODEL
ollama	OLLAMA_API_KEY optional	OLLAMA_MODEL

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.

Rules: the first connected provider becomes the default. Environment variables still take precedence over the saved key. Restart KODA to use the new provider (or set KODA_PROVIDER=name).

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.

COMMAND	DESCRIPTION
/help	Shows the built-in commands
/commands	Lists custom commands
/model [name\|number]	Switches the model
/agents	Lists agents
/agent [name]	Switches the primary agent
/skills	Lists skills
/connect [provider]	Saves a provider's API key
/clear	Clears the conversation context (asks for confirmation)
/exit	Exits KODA

Use @agent task to delegate to a subagent.

Agents

NAME	MODE	DESCRIPTION
build	primary	Default. All tools available.
plan	primary	Analyzes and proposes plans, without editing files.
general	subagent	Research and multi-step tasks.
explore	subagent	Read-only. Searches files and code.

Tools

TOOL	WHAT IT DOES
readFile	Reads files, with line ranges
writeFile	Creates or changes files (with approval)
listDirectory	Lists directories
searchFiles	Searches the project
getFileInfo	File metadata
runCommand	Runs commands with risk classification, bounded output and an allowlisted env

Custom commands

Create a Markdown file in .koda/commands/. The file name becomes the command.

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

Usage: /review src/index.ts security

Precedence (highest to lowest): .koda/ → koda.json → .opencode/ → opencode.json → global configuration. Duplicates at the same level cause an error.

Custom agents

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

---
description: Security reviewer
mode: subagent
model: anthropic/claude-3-5-sonnet-latest
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.

Use as a library

The package exports the SDK at dist/src/index.js.

import * as koda from "@koda-tools/koda";