Features
Everything Koda gives the agent CLIs — organized, persistent, and designed for running many of them at once. This page is a reference for each surface in the app and how to use it.
Workspaces
A workspace is any folder you open in Koda. It becomes a self-contained environment: your file tree, editor tabs, terminal layout, open panel, browser URL, and task board all belong to that workspace and survive restarts.
Organizing workspaces
The left switcher groups your projects into three categories you can drag between:
- Active — what you're working on now.
- Sensitive — marked with a 🔒. Sensitive workspaces are never auto-enabled for coordination, since that writes files into the repo.
- Archive — collapsed by default to keep the list clean.
Each workspace can be given a custom display name (inline rename) and reordered by dragging. Selecting a workspace does not reshuffle the list.
Persistence & templates
Layout and session state are written to <workspace>/.koda/session.json (debounced) and restored when you reopen. Open files survive in-session workspace switches; on a full restart, files are re-read fresh from disk and terminals respawn.
New workspaces can start from a template — Empty, Web app, Python/ML, or Claude feature dev — which seeds a few Kanban cards, opens the right panel, and can suggest a theme. Templates only write to .koda/; they never touch your project files.
.koda/ directoryKoda keeps all of its per-workspace state (session, board, coordination, env) in a .koda/ folder that is automatically gitignored. Your repository stays clean.Terminal panes
Terminals are the main stage. Each pane is a real shell (a PTY via node-pty), not a fake console — anything you'd run in your normal terminal runs here.
- Tiling — split the workspace into a live grid and run up to 8 panes side by side. Drag the dividers to resize and re-tile any way you like.
- Renameable — give each pane a name so a glance tells you what it's for.
- Copy / paste — Ctrl/Cmd+V (and Ctrl+Shift+V) paste. Ctrl/Cmd+C copies when text is selected, otherwise falls through to SIGINT — the same behavior as VS Code and Windows Terminal.
- Live theming — terminals recolor instantly when you switch themes; the cursor is tinted by the agent's accent color.
Agents
In Koda an agent is a launch command run inside a pane. Koda ships built-in profiles and lets you define your own.
Built-in agents
| Agent | Provider | Notes |
|---|---|---|
| Claude Code | Anthropic | Sign in with the real Claude Code CLI, or inject an API key. |
| OpenAI Codex | OpenAI | Subscription via CLI login, or API key. |
| Gemini | Vertex AI / AI Studio API key. | |
| Grok | xAI | Subscription via CLI login, or API key. |
| opencode | any | Any CLI-based agent. |
Custom agent profiles
Open Manage agents… (from the new-pane menu or the command palette) to define your own agent: a name, a launch command, an optional binary to detect, a provider (for vault key injection), an accent color, and a glyph. Custom agents are stored globally so they're available in every workspace, and they appear in both the new-pane menu and the Kanban agent picker.
Koda auto-detects which agent binaries are installed and only offers the ones it finds.
Kanban task board
The Tasks tab is a board where cards are work, not sticky notes. It's the engine that launches agents.
- Columns — Backlog → In Progress → Review → Done. Drag cards between them.
- A card carries a title, a prompt, an assigned agent, a status, and (once run) the pane it's running in.
- Run — hit Run and Koda spawns the chosen agent in a new pane, seeds it your prompt, and moves the card to In Progress automatically.
- Auto-advance — when that pane's process exits, the card moves to Review, ready for you to look at the result.
- Persistence — the whole board is saved per workspace in
.koda/board.json, ready when you return.
Monaco editor
The same editor core as VS Code, docked beside your agents in the Editor tab. Use it to review and tweak what your agents write without leaving Koda.
- Tabs with a dirty-dot indicator for unsaved changes.
Ctrl/Cmd+Sto save (bound as a Monaco command).- Syntax highlighting with language auto-detected from the file path.
- Themed live — the editor recolors with the rest of the UI.
File tree
A lazy, recursive file tree lives as a slim strip inside the Editor tab, scoped to your workspace. Click a file to open it in a new editor tab and focus the editor. The tree hides dotfiles, so .koda/ and other dot-directories stay out of view.
In-app browser
The Browser tab is a real embedded browser pointed at your dev server — preview your app right next to the agents building it, with no alt-tabbing.
- URL bar with back / forward / reload.
- Defaults to
http://localhost:3000; point it anywhere. - Watch the app update live as agents ship features.
Links that open new windows are sent to your OS browser, and the embedded view is locked down (no Node access in the guest content) for safety.
Credential vault
Store API keys once, encrypted by your operating system. Tag a key with a provider, and Koda injects it into that provider's panes at launch.
- OS-encrypted — keys are protected by your OS keychain (
safeStorage), bound to your OS user, and decrypted only inside Koda's main process — never exposed to the interface. - Provider-tagged injection — tag a key as Anthropic / OpenAI / Google / xAI and it's injected into the matching agent panes at spawn.
- Subscription-safe — if you don't tag a key for a provider, nothing is injected, so users signed in via the CLI subscription are never clobbered.
Themes
Koda ships 30+ built-in themes, dark and light, all hand-tuned. One click re-colors the entire app live — the UI, your terminals, and the Monaco editor all at once. Favorites include Tokyo Night (the default), Catppuccin, Dracula, Monokai, Solarized, One Light, and GitHub Dark.
Open the theme gallery from Settings → Appearance (the header gear) or the command palette; your choice persists across restarts.
Per-pane accounts
Run different logins in different panes. Assign a specific Claude account per terminal, so one pane uses your work subscription and another your personal — with no re-auth dance. Manage logins via Manage accounts… in the new-pane menu.
Under the hood each pane gets its own config directory, so accounts stay fully isolated between panes.
Environment variables
Inject custom environment variables into agent panes at spawn, from two sources that share one path:
- Per-agent — an env map on a custom agent, edited in the Agents modal. Travels with that agent everywhere.
- Per-workspace — stored in
.koda/env.json, edited via Workspace environment variables… in the command palette. Applies to every pane in that workspace.
When both define the same variable, the agent's value wins. Variables are applied at spawn, so reopen a pane to pick up edits.
KODA_PANE_ID, KODA_COORD_DIR, and CLAUDE_CONFIG_DIR itself — these can't be overridden by your env entries.Settings
Everything that used to live in scattered header buttons now folds into one place: a full-page Settings surface with a left tab rail. Open it from the gear in the header or via the command palette.
| Tab | What's there |
|---|---|
| Connections | Connect Claude Code, manage Claude accounts, and see which agent CLIs Koda detected on this machine. |
| MCP | Wire up external tool servers — see MCP Connections. |
| Appearance | The theme gallery — all 30+ palettes, applied live. |
| Credentials | The encrypted credential vault for API keys. |
| Account | Your Koda account and plan tier — sign in to unlock Pro. |
| About | Version, update status with a one-click Restart to update, and links. |
Account sign-in also lives at the bottom-left of the app, always in reach, showing your email and tier badge once you're in. No account is required to use Koda — signing in only unlocks paid features like code review.
Command palette
Press Ctrl/Cmd+K anywhere — even over a focused terminal — to open the command palette. Fuzzy-filter across grouped commands: open a new pane for any agent, create or switch workspaces, change the theme, open the vault, manage agents or accounts, and more. There's also a header button if you prefer the mouse.
Seamless updates
Koda keeps itself current. It checks GitHub Releases on launch and every 30 minutes, downloads updates in the background, and shows a status pill in the header. When an update is ready you get a Restart to update toast — one click installs it and relaunches. Update activity is logged locally so issues are diagnosable in packaged builds.
Usage meter (optional)
An optional header pill that shows your official Claude.ai usage — the real 5-hour and 7-day limit utilization and reset times, read straight from Claude.ai. It's there so you can see how much headroom you have before you start a long agent run, without leaving Koda.
It is strictly opt-in. Nothing happens until you paste your Claude.ai sessionKey once; with no session stored, the pill is absent and Koda makes no usage requests at all. You can disconnect it at any time, which deletes the stored session.
- OS-encrypted — the session is stored with your OS keychain (
safeStorage) in Koda's app-data folder, never in plaintext settings. - Validated & cached — Koda checks the session works before storing it, and caches the result briefly so it never hammers Claude.ai.
- Sent only to Claude.ai — the session is used solely to call Claude.ai's own usage API for your numbers. It goes nowhere else, and there is no Koda backend to send it to.