KODER — Terminal-Native AI Coding Agent

Overview

KODER is an AI coding agent that lives in the terminal. You point it at a project directory and it plans, reads, searches, edits, and runs commands through a streaming chat interface — with an explicit boundary between what it may read and what it may change. The architectural decision that shapes the whole system: the model runs on the server, but the tools run on your machine. The server owns the conversation, the model, and the tool *contracts*; the CLI owns execution. Your source code is never uploaded wholesale — only the specific tool results the model asks for cross the wire.

Core Features

•PLAN / BUILD modes — PLAN is strictly read-only (readFile, listDirectory, glob, grep), while BUILD unlocks writeFile, editFile, and bash. The mode gates tool availability at both contract and execution level.
•Multi-provider model support across Anthropic, OpenAI, OpenRouter, and Groq, switchable mid-session; only the key for the selected model is required.
•Agentic tool loop — the model requests a tool, the CLI executes it locally, the result feeds back, and the loop continues until the turn resolves.
•Browser-based OAuth login via Clerk using a PKCE public-client flow, so the CLI authenticates without ever handling a password.
•Persistent sessions stored in Postgres, browsable and resumable, with per-message metadata for mode, model, duration, and token usage.
•Terminal UI with themes, a command palette, slash commands (/new, /login, /models, /agents, /sessions, /theme), and a live status bar.

System Architecture

A Bun monorepo of four packages:

•packages/cli — OpenTUI + React terminal client. Renders the UI and executes every tool locally against the working directory.
•packages/server — Hono API handling auth, sessions, and chat streaming via the Vercel AI SDK.
•packages/shared — The contract layer: modes, Zod tool schemas, and the model catalog, shared by both ends so client and server cannot disagree about what a tool looks like.
•packages/database — Prisma schema and client over Postgres.

Safety Model

•Every filesystem path is resolved and checked against the working directory, and any path escaping it is rejected — the agent cannot read or write outside the project it was opened in.
•PLAN mode re-validates tool permissions at execution time, not just when the tool list is sent to the model, so a model that hallucinates a write tool in read-only mode still gets refused.
•Tool outputs are bounded — file reads, search matches, directory listings, and command output are all capped and truncated, and shell commands run under a timeout.

Key Challenges

•Splitting the agent loop across a network boundary — the server streams tool *calls*, the client executes them and streams results back, while both sides keep a consistent view of message state.
•Designing tool contracts once in a shared package so the model's schema, client execution, and server validation stay in lockstep.
•Implementing OAuth for a CLI, where there is no browser to redirect and no safe place to keep a secret — solved with a PKCE public-client flow and a local callback.
•Building a responsive interface with React reconciliation driving a terminal rather than a DOM.
•Enforcing sandboxing that holds against path traversal while still feeling unrestricted inside the project.

Key Learnings

•Agentic loop design — tool contracts, multi-step tool calling, and streaming partial state to a UI.
•Provider-agnostic LLM integration through a single abstraction over four vendors.
•Terminal UI development with React outside the browser.
•OAuth flows for native and CLI clients, including PKCE and token storage.
•Capability-based security: modeling permissions as tool availability rather than after-the-fact checks.

Impact

•Delivered a working coding agent covering the full stack — terminal UI, agent loop, tool sandbox, auth, and persistence.
•Designed a client-side execution model that keeps source code local while still using hosted models.