Docs / Getting Started

Koda documentation

Koda is a desktop agentic development environment (ADE) — a workspace built around coding agents. You run the real agent CLIs in tiled terminals, launch their work from a Kanban board, and they coordinate with each other automatically. This guide covers everything from install to the multi-agent coordination layer.

Install Koda

Download the desktop app and open your first workspace.

Start →

Explore features

Panes, agents, board, editor, browser, vault & themes.

Features →

Coordination / MCP

How agents auto-announce, claim work, and stay in sync.

Learn →

Introduction

Koda is a terminal/CLI orchestrator. Each pane in Koda is a real PTY shell, and an "agent" is simply a launch command — claude, codex, gemini, and others — run inside one of those shells. Koda gives those agent CLIs a polished, organized home: tiling workspaces, a built-in editor and browser, an encrypted credential vault, a task board that launches agents, and a coordination layer that lets many agents work together without colliding.

Koda is built on Electron, React and TypeScript. It runs entirely on your machine — your code, your shells, and your agents never touch a Koda server.

◆

The one-sentence modelKoda doesn't replace your agents — it hosts them. You bring the CLIs you already use; Koda gives them a workspace, a task board, and a way to talk to each other.

Installation

Koda is a desktop application. The Windows installer is available today and updates itself in the background; macOS and Linux builds are on the way.

Download the latest installer from the releases page.
Run the installer (Koda-x.y.z-setup.exe on Windows). It's an assisted install — pick a location or accept the default.
Launch Koda — no account is required to start. You can sign in at any time to unlock Pro features, but the free tier works fully without an account.

You also need at least one agent CLI installed and on your PATH — for example Claude Code (claude), OpenAI Codex (codex), Gemini, Grok, or opencode. Koda detects which ones are present and offers them when you create a pane.

✓

Auto-updatesOnce installed, Koda checks for new releases on launch and every 30 minutes. When an update is downloaded you get a "Restart to update" prompt — one click and you're on the latest build.

First run

The first time you open Koda, an onboarding flow walks you through four quick steps:

Welcome — a short tour of what Koda is.
Pick a theme — choose from 30+ palettes; the whole app recolors live.
Providers — Koda detects installed agent CLIs, lets you sign in to Claude Code, or paste an API key straight into the encrypted vault.
Create a workspace — open a folder and optionally start from a template (Empty, Web app, Python/ML, or Claude feature dev) that seeds a few Kanban cards.

After onboarding you land in your first workspace: the terminal grid is the main stage, with a collapsible side panel on the right holding the Browser, Editor, and Tasks tabs.

Core concepts

A handful of ideas show up everywhere in Koda. Understanding them makes the rest of the docs click.

Workspace

A folder you've opened. Holds your panes, layout, board, and session — all persisted under a local .koda/ directory.

Pane

One tile in the terminal grid: a real shell. Resizable, renameable, and the home of a single agent.

Agent

A launch command run inside a pane (e.g. claude). Built-in profiles plus your own custom ones.

Card

A unit of work on the Kanban board. Carries a title, a prompt, an assigned agent, and a status.

Lane

An agent's declared area of responsibility (e.g. backend · src/api) so peers stay out of each other's files.

Coordination

The MCP bus that lets agents read the board, claim work, and message each other. On by default.

Review

A diff of everything an agent changed since it started, with line comments and an Approve / Request-changes verdict. A Pro feature.

Connection

An external MCP tool server (docs, search, analytics…) wired into your workspaces so agents can call it.

How Koda stays compliant

Koda runs the real first-party CLIs in real terminals. This is a deliberate, locked architectural decision and it shapes everything:

Koda does not make API calls on your behalf.
Koda does not proxy, read, or reuse your OAuth tokens.
Koda does not sit between you and your provider.

You sign in to your tools exactly as you always have — through the CLI itself. Because Koda only spawns the real CLI, using your own subscription inside it is ordinary individual usage. Your credentials never leave your device, and the coordination layer is a local tool server the CLIs choose to call — never a token proxy.

▲

The line Koda never crossesNo "Sign in with Claude" flow, never reading or reusing the token in your provider's credentials file, and never proxying a provider's API with subscription credentials.

There is exactly one opt-in exception, and we name it openly: the optional usage meter. If — and only if — you choose to connect it, it reuses your own Claude.ai web session to read your own usage numbers. It's off until you connect it, the session stays OS-encrypted on your machine, and you can disconnect it anytime. Nothing else in Koda reads a provider credential.