Koda

:::    ::: ::::::::  :::::::::      :::
:+:   :+: :+:    :+: :+:    :+:   :+: :+:
+:+  +:+  +:+    +:+ +:+    +:+  +:+   +:+
+#++:++   +#+    +:+ +#+    +:+ +#++:++#++:
+#+  +#+  +#+    +#+ +#+    +#+ +#+     +#+
#+#   #+# #+#    #+# #+#    #+# #+#     #+#
###    ### ########  #########  ###     ###

Features

• Autonomous pair-programming — Koda reads your project structure, understands the architecture, and edits files directly. No copy-paste required.
• Modern UI by default — opens in the sleek Modern Pro layout with Iconbar on first launch. Classic CLI mode is still available via Settings.
• Onboarding tour — first-time users get an interactive guided tour highlighting the CWD selector, chat input, mode switcher, workspace split button, and Iconbar. Appears once and is dismissed to localStorage.
• Chat history — per-project session history stored in localStorage. Hover the Iconbar to open the history panel, load a past session, or delete it. Each conversation is a separate session file — no overwriting.
• User messages aligned right — in Modern UI, user messages appear as chat bubbles on the right side. Rollback action appears below on hover.
• Multi-Workspace Split Mode — run multiple independent agent sessions side-by-side in the same window. Each workspace has its own conversation, project context, terminal, and file tracker — with zero cross-talk between instances.
• Snapshot & rollback — before every message, Koda captures a full in-memory snapshot of all workspace files. Hover any user message and click ↺ to restore both files and agent memory to that exact point.
• Task queue — send the next task while the agent is still working. Koda queues it and fires it automatically when the current task finishes.
• Real PTY terminal — native shell integration via node-pty. Koda spawns background processes, waits for output patterns, sends stdin, and kills processes by PID — all autonomously.
• Interactive terminal panel — a full xterm.js terminal for you to use directly, independent of the agent, with resize support and ANSI rendering.
• Built-in browser preview — a <webview>-based browser panel with navigation controls, defaulting to localhost:5173.
• Web navigation agent — via operantid.js, Koda can spawn a sub-agent that controls a real browser to navigate, interact with UI elements, and extract data from websites.
• Questions tool — the agent can ask up to 10 clarifying questions before acting. Presented one at a time as a wizard panel above the chat input, supporting single and multiple-choice options. Blocks execution until all answers are submitted.
• Shell approval panel — shell approval requests appear as an inline panel above the chat input. Shows the command with Accept (Once / Base / Full) and Deny buttons.
• .kodaignore support — create a .kodaignore file in your project root (same syntax as .gitignore) to restrict Koda's access to specific files or folders. Blocked paths are invisible in list_dir, file_find, and search. If the agent tries to read or write a blocked path directly, it receives a clear access-denied message instead of the file content.
• 4 operation modes — Fast, Planner, Colab, and Teach & Code, selectable from a dropdown in the TitleBar.
• Skills system — Markdown-based skill files inject specialized instructions into the agent's context on demand. Invoke with /skill-name or let the agent load them autonomously. Global skills in ~/.koda/skills/, project-local in .koda/skills/.
• Dynamic slash menu — typing / opens a live-filtered dropdown listing all native commands and available skills.
• Inline diff viewer — file_edit outputs render as a side-by-side visual diff with line numbers.
• System notifications — native OS notification fires when a long task (>3s) completes and the window is not in focus.
• Remote Control API — built-in HTTP server (default port 3141) exposes POST /task, GET /status, POST /reset, and GET /messages.
• MCP support — connect any Model Context Protocol server. Tools are discovered at runtime and injected into the agent's arsenal dynamically.
• LSP integration — semantic queries via typescript-language-server: hover types, go-to-definition, and symbol resolution.
• 16 LLM providers — dynamic model listing via API. Switch providers and models from the UI without restarting.
• File tracker — every file the agent reads or modifies is tracked in-session and surfaced in the context panel.
• At-mentions (@) — type @ to open a file selector. Koda reads the file and injects it directly into the prompt (capped at 50KB).
• Drag & drop — drop image files to attach them; drop code files to inject an @[path] mention.
• Configurable verbosity — toggle output visibility per tool type without affecting agent context.
• 4 built-in themes — Tokyo Night, GitHub Dark, Cyberpunk Neon, Monokai. Live preview, fully customizable.
• 32-bit Windows support — separate installers for x64 and ia32 architectures, built independently via GitHub Actions.
• macOS compatibility — DMG built without code signing requirements. If Gatekeeper blocks the app, run xattr -cr /Applications/Koda.app to remove the quarantine attribute.

Operation Modes

Switchable from the TitleBar via a dropdown selector.

⚡ Fast (default)

Immediate autonomous execution. The agent acts on your request without any planning step.

📋 Spec Development

Before writing any code, Koda enters a read-only exploration cycle and drafts a full specification file (specs.md) at the root of your project. A modal appears for you to Approve or Reject the spec. No files are modified until approval is granted.

👥 Colab

Activates three additional tools: start_collaboration, send_to_advisor, and end_collaboration. Koda can open a multi-turn conversation with a second model instance to brainstorm architecture before implementing.

🎓 Teach & Code

Koda acts as a technical mentor. For every non-obvious change, it explains why that approach was chosen over alternatives. Ideal for learning a codebase.

Multi-Workspace

Koda supports running multiple, fully isolated agent sessions inside a single window.

Activating Split Mode

Click the split panel icon (⊞) in the TitleBar, to the right of the mode selector. A tab bar appears. Each tab represents an independent workspace.

Creating & Managing Workspaces

• + — creates a new workspace with a fresh agent instance.
• Click a tab — switches the active workspace instantly.
• ✕ on a tab — closes that workspace. The last workspace cannot be closed.

Isolation Guarantees

.kodaignore

Create a .kodaignore file in your project root to restrict what Koda can access. Uses the same syntax as .gitignore:

# Secrets
.env
*.key
secrets/
config/private.json

# Sensitive directories
private/

Behavior per tool:

The agent knows the file exists but cannot see its content — it will not attempt workarounds.

Tool Arsenal

All tools extend BaseTool and are registered in ToolRegistry. The registry enforces mode restrictions and plan-mode write locks before every execution.

Supported Providers

Installation

Prerequisites

• Node.js 20 or higher
• Git in your PATH
• An API key from any supported provider (or use Koda Cloud)

Development

git clone https://github.com/antojunimaia-ui/Koda.git
cd Koda
npm install
npm run dev:clean

Use dev:clean to wipe dist-electron/ before starting. Stale build artifacts cause subtle IPC failures.

API keys are stored in localStorage via the settings panel. No .env file is required for the UI.

Environment Variables (optional)

LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-...
ANTHROPIC_MODEL=claude-sonnet-4-20250514
MAX_TOKENS=8192
TEMPERATURE=0.3

Native Commands

Remote Control API

Enable in Settings → Remote Control.

curl -X POST http://100.x.x.x:3141/task \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"message": "run the test suite and fix any failures"}'

Tasks sent via the API appear in chat with a 🌐 Remote badge.

Build & Distribution

# Windows x64 — NSIS installer
npm run dist

# Windows ia32 (32-bit) — separate installer
npm run dist:32

# Linux — AppImage
npm run dist:linux

# macOS — DMG
npm run dist:mac

Output goes to release-build/. GitHub Actions builds x64 and ia32 as completely separate jobs, producing:

• Koda-Setup-<version>-x64.exe
• Koda-Setup-<version>-ia32.exe

macOS note: If Gatekeeper shows "app is corrupted", run xattr -cr /Applications/Koda.app in Terminal to remove the quarantine attribute.

Architecture

src/
├── main/                        # Electron Main Process (Node.js)
│   ├── index.ts                 # App bootstrap + all IPC handlers (workspace-aware)
│   ├── core/
│   │   ├── agent.ts             # Agent class: provider lifecycle, message loop, tool orchestration
│   │   ├── conversation.ts      # Message history, microCompact, trimIfNeeded, rollback
│   │   ├── prompt-builder.ts    # Dynamic system prompt assembly (env + project + tools)
│   │   └── context.ts           # Project detection (language, framework, package manager)
│   ├── providers/               # 15 LLM provider implementations (all extend BaseProvider)
│   │   └── base.ts              # BaseProvider, Message, StreamChunk, ToolCall interfaces
│   ├── tools/                   # 19 agent tools (all extend BaseTool)
│   │   ├── index.ts             # ToolRegistry: registration, mode filtering, plan-mode lock
│   │   ├── shell.ts             # ShellTool + PTY registry + KillPty/ListPty/ShellInput/ShellWait
│   │   ├── file-edit.ts         # String-replace edit with unified diff output
│   │   ├── collaborate.ts       # Advisor LLM session (StartColab/SendColab/EndColab)
│   │   ├── plan.ts              # Plan mode state machine + approval Promise
│   │   ├── questions.ts         # Questions tool — wizard panel, blocks via Promise
│   │   └── mcp-tool.ts          # Dynamic MCP tool wrapper
│   ├── services/
│   │   ├── snapshot.ts          # In-memory workspace snapshots (create/restore/list)
│   │   ├── mcp-manager.ts       # MCP server lifecycle + JSON-RPC tool discovery
│   │   ├── lsp-client.ts        # typescript-language-server client
│   │   ├── file-tracker.ts      # In-session file access tracker
│   │   ├── skill-manager.ts     # Loads .md skills from ~/.koda/skills/ and .koda/skills/
│   │   └── webhook-server.ts    # HTTP remote control server
│   ├── config/
│   │   └── settings.ts          # AppSettings, .env loading, provider defaults
│   └── utils/
│       ├── diff.ts              # Unified diff generation + string-replace logic
│       ├── kodaignore.ts        # .kodaignore parser + path filter (minimatch-based)
│       ├── tokens.ts            # Token estimation
│       ├── syntax.ts            # Language detection from file extension
│       └── logger.ts            # Logging utilities
├── preload/
│   └── index.ts                 # contextBridge: exposes window.koda API
└── renderer/                    # React 19 + Tailwind CSS 4
    ├── App.tsx                  # Root orchestrator: multi-workspace state, session routing, IPC wiring
    ├── types/index.ts           # Workspace, AgentInfo, MessageEntry and all shared interfaces
    ├── hooks/
    │   ├── useAgentStream.ts    # IPC event subscriber — per-workspace chunk buffers + RAF flush loops
    │   ├── useSession.ts        # Project session load — workspace-isolated CWD tracking
    │   └── useSessionStorage.ts # localStorage-based session persistence (list/save/delete)
    └── components/
        ├── modern/ModernUI.tsx  # Default UI: sleek backdrop-blur interface with Iconbar
        ├── classic/ClassicUI.tsx# Alternative UI: cyberpunk terminal-inspired interface
        ├── OnboardingTour.tsx   # First-launch guided tour (5 steps, arrow tooltips)
        ├── ChatHistory.tsx      # Per-project session history panel (hover Iconbar to open)
        ├── modals/
        │   ├── PlanApprovalModal.tsx  # Plan approval overlay
        │   ├── QuestionsModal.tsx     # Questions wizard panel
        │   └── ShellApprovalPanel.tsx # Shell approval panel
        ├── messages/
        │   ├── UserMessage.tsx        # Right-aligned bubble in Modern UI, rollback on hover
        │   └── CompactToolView.tsx    # Grouped tool summary view
        ├── WorkspaceTabs.tsx    # Tab bar for switching/creating/closing workspaces
        ├── TitleBar.tsx         # Mode switcher + Workspace Split toggle + window controls
        ├── TerminalPanel.tsx    # xterm.js terminal connected to a live PTY
        ├── BrowserPreview.tsx   # Electron <webview> browser panel
        ├── MCPSettings.tsx      # MCP server configuration UI
        └── BrailleSpinner.tsx   # Animated thinking indicator

Contributing

Read CONTRIBUTING.md before opening PRs. Key points: strict TypeScript (avoid any), focused PRs (one thing per PR), Conventional Commits, and never commit API keys.

License

Distributed under the BSD 3-Clause License.