Koda
The Review-First, Collaborative Agent IDE
Koda runs Codex or Claude sessions in isolated git worktrees on your Mac. Share a workspace and a teammate opens it from their own Koda. They see the same transcript and tool calls live, and with control they can message the agent too. Their message lands in your session, signed with their name.
Watch the 35-second recording of one Claude session shared live between two Macs.
Quick Start
Prerequisites
- Node.js 24 recommended (22.12+ required)
- pnpm 9+
- Rust toolchain (for Tauri)
- macOS (Windows/Linux support planned)
- An installed Codex CLI, signed in with
codex login
- For Claude: an installed Claude CLI, signed in with
claude auth login
Install
git clone https://github.com/gorkamolero/koda.git
cd koda
pnpm install
Run
# Start the desktop app (launches sidecar automatically)
pnpm app
# Or run components separately:
pnpm desktop # Tauri desktop shell
pnpm sidecar # Node.js orchestration layer
Codex is the default agent. New chats can select Codex or Claude, with a separate model picker for each. Koda uses the installed Codex CLI app-server and the official Claude Agent SDK; saved sessions retain their agent, model, and permissions across restarts. Claude authentication stays with the local Claude CLI. See the dated authentication research in VERIFY.md.
Choose the default for new conversations in Settings → Agent → New conversation permissions. This setup defaults to Bypass permissions, with Ask when needed also available. Each new chat starts with that preference and can override it; existing chats retain their saved mode. Requests needing permission show Approve once and Deny. Bypass lets tools run outside the worktree without asking and also applies to collaborators with control. Provider-enforced restrictions still apply.
Settings also recommends Destructive Command Guard, an optional hook that blocks known destructive commands. It requires separate installation; its Codex coverage is incomplete and it is not a sandbox.
When Codex or Claude asks a structured question, answer its form in the host chat. Forms support single choices, Claude multiple choices, and custom answers. Submit answers resumes the agent; Cancel and stop ends the turn. Bypass permissions still waits for your answers. Pending forms return after a UI reload while the sidecar stays running; unfinished answer drafts are not saved.
For collaboration, choose a display name in Settings → Collaboration. The hosted default is https://koda-collaboration.gorka-molero.workers.dev; no service configuration is required. Override it under Advanced or with KODA_COLLAB_URL. Your first share registers this install automatically; collaborators need no Liveblocks key. Open a worktree's Share workspace dialog to create a control or view invitation; the other instance joins through Shared workspaces. Both installs must use the same service.
Each install keeps its device private key and host invitation key in its private local state. The hosted Cloudflare Worker holds the Liveblocks secret and authorizes only owned or granted rooms. LIVEBLOCKS_SECRET_KEY alone does not change modes. Trusted development setups must explicitly set KODA_COLLAB_MODE=development and supply LIVEBLOCKS_SECRET_KEY. The owner can redeploy the Worker with pnpm collab:deploy. See VERIFY.md for local testing and owner deployment.
See VERIFY.md for the real-service proofs, screenshots, separate-instance setup, and clean-clone verification.
Test
pnpm test # Run UI, Worker, sidecar and desktop unit tests
pnpm --filter @koda/sidecar test # Sidecar unit tests
pnpm --filter e2e test:proof # Maintained real-service proofs (Playwright)
Storybook
The shared @koda/ui package documents Koda's four themes and all 40 design-system component groups, with props, variants, keyboard interactions and accessibility tests. Explore the foundations, brand, collaboration patterns, and composed host/collaborator workspace screens.
pnpm storybook # Local explorer at http://localhost:6006
pnpm build-storybook # Static build
pnpm --filter @koda/ui exec playwright install chromium
pnpm test-storybook # Browser stories and accessibility checks
Public Storybook: gorkamolero.github.io/koda, on GitHub Pages. pnpm storybook:pages builds it and publishes it to the gh-pages branch.
Desktop now composes @koda/ui across navigation, agent chat, workspace panels, settings and sharing. Feature components retain data and permissions; shared components are presentational. The duplicate primitives and unused AI elements are removed, and token lint is enforced as an error. See DESIGN.md and the migration verification record.
Architecture
┌────────────────────────────────────────────────────────────┐
│ Koda Desktop (Tauri 2.x) │
│ ┌─────────────────────┐ ┌─────────────────────────────┐ │
│ │ React Frontend │ │ Native Rust Layer │ │
│ │ - Monaco Editor │ │ - File System (fast) │ │
│ │ - Diff View │ │ - Git Operations │ │
│ │ - Workspace UI │ │ - IPC Bridge │ │
│ └──────────┬──────────┘ └─────────────────────────────┘ │
└─────────────┼──────────────────────────────────────────────┘
│ Unix Socket (JSON-RPC 2.0)
▼
┌────────────────────────────────────────────────────────────┐
│ Orchestration Sidecar (Node.js) │
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
│ │ Claude Agent │ │ Codex Agent │ │ Kimi Agent │ │
│ └────────────────┘ └────────────────┘ └────────────────┘ │
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
│ │ SQLite DB │ │ PTY Manager │ │ Git Worktrees │ │
│ └────────────────┘ └────────────────┘ └────────────────┘ │
└────────────────────────────────────────────────────────────┘
Project Structure
koda/
├── apps/
│ ├── desktop/ # Tauri + React frontend
│ │ ├── src/ # React components
│ │ └── src-tauri/ # Rust native layer
│ └── sidecar/ # Node.js orchestration
│ ├── src/
│ │ ├── handlers/ # Agent handlers (Claude, Codex, Kimi)
│ │ ├── db/ # SQLite schema + migrations
│ │ └── rpc/ # JSON-RPC router
│ └── tests/
├── packages/ui/ # Shared tokens, components and Storybook
├── e2e/ # Playwright E2E tests
├── docs/ # Extended documentation
├── SPEC.md # Full architecture spec
├── FEATURES.md # Feature roadmap
└── API.md # RPC method reference
Core Concepts
Workspaces
Isolated environments for agent work. Each workspace is a git worktree with its own branch, agent sessions, and state.
Agent Sessions
Conversations with Codex or Claude retain their messages, selected model, and upstream agent session for continuation after restarts. Workspaces can be shared with view or control access. Kimi and cross-agent conversation forks are outside the verified flow.
Checkpoints
Save a worktree snapshot from the chat and restore it when needed. Saving a checkpoint preserves the working files and staging index.
Visual Diffs
Not just code diffs — before/after screenshots of your running app. See what changed visually.
Documentation
Tech Stack
| Layer | Technology |
|---|
| Desktop Shell | Tauri 2.x (Rust) |
| Frontend | React 18, Vite, TailwindCSS |
| Editor | Monaco |
| Sidecar | Node.js, TypeScript |
| Database | SQLite (better-sqlite3) |
| IPC | JSON-RPC 2.0 over Unix sockets |
| Testing | Vitest, Playwright |
License
MIT
Built by Gorka.
