README
¶
koder
Local-first coding and computer use agent. It runs as a single local Go process, serves multiple sessions via browser UI, and connects to your choice of OpenAI-compatible model providers.
Nice features from being browser based: multiple live sessions, rich chat rendering, visual file browsing, planning boards, model settings, permissions, TTS controls, approvals, debug traces, and repo state all stay visible and inspectable.
Author's current setup: Linux, local llama.cpp, Qwen 3.6 27B Q8 for 256K-token chat sessions, and a Qwen 3.5 4B summarizer model for compaction.
Use Cases
- Software development in real repositories. Let the agent inspect code, search with structured tools, make targeted edits, run checks, explain failures, and keep a persistent trail of what changed.
- Long-running investigations. Keep multiple chats open for hypotheses, experiments, review, and follow-up while the session preserves tool output, approvals, summaries, and context usage.
- Reverse engineering and security research. Use repo tools, command execution, notes, file browsing, image viewing, and planning boards to work through unfamiliar code, binaries, traces, protocols, and generated artifacts.
- Designing generated objects with visual feedback. Iterate on things like OpenSCAD models, diagrams, generated images, reports, or markdown documents while both user and model can inspect rendered output.
- Local-model workflows. Run against
llama.cppor another OpenAI-compatible provider, tune custom model request JSON, use prompt-progress diagnostics, and keep sensitive work on your own machine. - Planning and delegating larger work. Track milestones and tasks in the UI while an orchestrator chat manages scope and controlled execution chats handle focused pieces.
Screenshots
Quick Start
Download the latest Linux x64 or Linux arm64 build from GitHub Releases:
chmod +x koder-rNNNN-linux-amd64
./koder-rNNNN-linux-amd64 serve
Or build from source:
git clone https://github.com/lkarlslund/koder.git
cd koder
scripts/build-koder
.bin/koder serve
By default, Koder binds to a local ephemeral port and opens your browser. To choose the address or keep the browser closed:
koder serve --web-bind 127.0.0.1:8080
koder serve --nobrowser
To expose the Android voice endpoint on your LAN, bind Koder to the LAN and set a dedicated bearer token:
KODER_VOICE_TOKEN='replace-with-a-long-random-token' \
koder serve --web-bind 0.0.0.0:7979 --nobrowser
The Android client connects to ws://<computer-address>:7979/voice/v1. Do not
expose an unencrypted ws:// endpoint beyond a trusted private network.
Android streams microphone and playback PCM; Koder performs STT and TTS through
the OpenAI-compatible providers selected in [voice]. See the
Android setup,
as-built architecture, and
voice.v1 contract.
Use a separate data directory when testing another instance:
koder --data-dir /tmp/koder-test serve --web-bind 127.0.0.1:7980 --nobrowser
Check configuration and provider connectivity:
koder doctor
Providers And Models
Koder does not require a specific hosted service. Configure providers in Preferences or in config.toml, then choose the default model in the UI.
Example local llama.cpp provider:
[defaults]
provider_id = "local-llama"
model_id = "qwen3-coder"
[compaction]
auto_at_percent = 85
use_chat_model = true
[providers.local-llama]
kind = "openai-compatible"
name = "Local llama.cpp"
base_url = "http://127.0.0.1:8888/v1"
stream = true
timeout = "10m"
[[models]]
provider_id = "local-llama"
model_id = "qwen3-coder"
context_window = 32768
Detected models are read-only. If a model needs special request settings, create a custom model from it and edit the JSON request options in the model dialog. Koder can use separate models for chat, compaction, thinking helpers, and TTS when that is useful.
How It Works
Each session has its own repository root, chats, settings, permissions, transcript, and file watcher. The browser UI talks to the local Koder process over HTTP and WebSocket. The Koder process talks to the selected model provider and executes approved local tools.
The model sees a structured tool surface instead of a vague shell-only environment:
| Area | Tools and behavior |
|---|---|
| Repository understanding | read, glob, grep, code search, file tree browsing, image viewing |
| Editing | targeted edit, explicit full-file write, post-edit diagnostics where supported |
| Execution | shell commands, long-running exec sessions, command output capture, exit codes |
| Planning | milestones, tasks, status updates, planning board, controlled sub-chats |
| Context | context tracking, compaction, image-capability checks, prompt-progress diagnostics |
| Browser and extensions | Native shared Chrome automation, web fetch/search, MCP tools, skills, markdown and Mermaid validation |
Feature Highlights
| Feature | What it is for |
|---|---|
| Browser-native multi-session workspace | Keep several repositories, chats, and investigations open in one local process without pretending everything is one terminal buffer. |
| Shared human/agent planning board | Milestones and tasks are editable by both the user in the UI and the model through tools, so planning state is not trapped in chat prose. |
| Controlled background execution chats | Let an orchestrator chat stay in charge while scoped sub-chats execute work, with limits on concurrent non-idle child chats. |
| Descriptive chat status | Chats can publish a durable objective, phase, blocked flag, and optional progress independently of runtime states such as reasoning, streaming, or idle. |
| Queue, steer, and send-now controls | Add normal queued messages, steer a running turn, promote/demote queued messages, or abort the current turn and send a new instruction immediately. |
| Visual artifact feedback loop | Browse rendered markdown, Mermaid diagrams, images, and generated files so both user and model can iterate on visual output, not just raw text. |
| Native shared browser automation | Drive one visible authenticated Chrome profile with chat-owned tabs, snapshots, interactions, screenshots, console and network inspection. Screenshots flow directly into model vision and the UI without Node.js or workspace temp files. |
| Local model diagnostics | Detect llama.cpp context/slot behavior, show prompt-progress/cache signals, and expose provider HTTP traces when cache reuse or streaming looks wrong. |
| Custom model variants | Create derived models with custom request JSON, defaults, TTS settings, thinking settings, and compaction choices without changing the backing provider. |
| Explicit sandbox safety controls | Permissions, network policy, workspace access, and model choices remain session-scoped; a separate global folder allowlist can expose narrowly selected caches or SDKs to every sandbox. |
| Inspectable persistence and debug API | Local transcripts, tool output, approvals, planning data, events, and HTTP traces remain available for review and troubleshooting after long runs. |
Requirements
- Linux x64 or Linux arm64 for release binaries.
- Go toolchain when building from source.
- At least one OpenAI-compatible model provider.
rgis optional; search falls back to a Go implementation when ripgrep is unavailable.bwrapis currently required for sandboxed shell command execution on Linux.- Chrome or Chromium and
bwrapare required for native browser automation. Node.js and Playwright are not runtime dependencies. - macOS and Windows can run the web UI and non-shell features, but shell sandboxing is currently Linux-oriented.
Folders such as ~/.cache or ~/go/pkg/mod can be shared without exposing the rest of the home directory under Settings → Access → Folders shared with every session. Each grant is independently read-only or read-write, applies to existing and new Koder and Codex chats, and can also be configured with [[global_mounts]] entries in config.toml.
Useful Commands
koder serve
koder --data-dir /tmp/koder-test serve
koder serve --web-bind 127.0.0.1:8080
koder serve --nobrowser
koder doctor
koder doctor --provider local-llama --model qwen3-coder
koder doctor --tts
koder debug info
koder debug tail --session <session-id> --url http://127.0.0.1:7979
koder session --help
koder skill --help
koder version
Debug API
Koder exposes debug endpoints on the same web server as the UI. If the UI is running at http://127.0.0.1:44323, the debug API is under http://127.0.0.1:44323/debug.
Useful endpoints include:
/debug/runtime/debug/sessions/debug/sessions/<id>/transcript/debug/sessions/<id>/events/debug/chats/debug/http
See docs/debug-api.md for details.
Build
For normal local development:
go test ./...
go build ./cmd/koder
For release-style build metadata in koder version and the debug API:
scripts/build-koder
That injects version, commit, dirty state, and build time into the binary with Go linker flags.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
koder
command
|
|
|
internal
|
|
|
androidupdate
Package androidupdate exposes the signed Android client embedded in Koder.
|
Package androidupdate exposes the signed Android client embedded in Koder. |
|
chatinteraction
Package chatinteraction defines behavior that belongs to an interaction surface rather than to the model backend or workflow role.
|
Package chatinteraction defines behavior that belongs to an interaction surface rather than to the model backend or workflow role. |
|
codexapp
Package codexapp implements the Codex app-server JSONL transport.
|
Package codexapp implements the Codex app-server JSONL transport. |
|
deviceauth
Package deviceauth owns persistent per-device voice credentials and short-lived invitations used to bind an Android installation.
|
Package deviceauth owns persistent per-device voice credentials and short-lived invitations used to bind an Android installation. |
|
memory
Package memory defines Koder's canonical durable-memory domain.
|
Package memory defines Koder's canonical durable-memory domain. |
|
memory/api
Package memoryapi defines the stable JSON boundary used by Memory HTTP clients.
|
Package memoryapi defines the stable JSON boundary used by Memory HTTP clients. |
|
memory/curation
Package curation schedules provider-independent extraction of durable-memory candidates from completed chat turns.
|
Package curation schedules provider-independent extraction of durable-memory candidates from completed chat turns. |
|
memory/curationadapter
Package curationadapter connects provider-neutral curation contracts to the Memory service without making either package depend on chat/model implementations.
|
Package curationadapter connects provider-neutral curation contracts to the Memory service without making either package depend on chat/model implementations. |
|
memory/embedding
Package embedding provides optional adapters for deriving Memory vectors.
|
Package embedding provides optional adapters for deriving Memory vectors. |
|
memory/kpackage
Package kpackage implements Koder's portable .kmemory container format.
|
Package kpackage implements Koder's portable .kmemory container format. |
|
memory/migrationarchive
Package migrationarchive serializes backend-neutral Memory snapshots without exposing any persistence backend's private files, keys, or index layout.
|
Package migrationarchive serializes backend-neutral Memory snapshots without exposing any persistence backend's private files, keys, or index layout. |
|
memory/observability
Package observability records privacy-safe Memory operation metrics and correlation identifiers.
|
Package observability records privacy-safe Memory operation metrics and correlation identifiers. |
|
memory/service
Package service is the only application-facing boundary for durable Memory.
|
Package service is the only application-facing boundary for durable Memory. |
|
memory/store
Package store defines the persistence contract consumed by the Memory service.
|
Package store defines the persistence contract consumed by the Memory service. |
|
memory/store/internal/revision
Package revision implements optimistic-revision checks shared by Memory stores.
|
Package revision implements optimistic-revision checks shared by Memory stores. |
|
memory/store/memory
Package memory provides a deterministic in-memory Memory store for service and backend-contract tests.
|
Package memory provides a deterministic in-memory Memory store for service and backend-contract tests. |
|
memory/store/migration
Package migration coordinates resumable, rollback-capable store schema migrations.
|
Package migration coordinates resumable, rollback-capable store schema migrations. |
|
memory/store/pebble
Package pebble implements the private Pebble persistence format for Koder Memory.
|
Package pebble implements the private Pebble persistence format for Koder Memory. |
|
phonedevice
Package phonedevice owns permission-gated Android tool providers connected to active voice conversations.
|
Package phonedevice owns permission-gated Android tool providers connected to active voice conversations. |
|
tools/chatstatustool
Package chatstatustool publishes descriptive chat activity to users and coordinators.
|
Package chatstatustool publishes descriptive chat activity to users and coordinators. |
|
tools/memorytool
Package memorytool exposes Koder's durable memory graph through one model-facing, multi-action tool.
|
Package memorytool exposes Koder's durable memory graph through one model-facing, multi-action tool. |
|
voice
Package voice coordinates ephemeral voice calls with ordinary Koder sessions.
|
Package voice coordinates ephemeral voice calls with ordinary Koder sessions. |
|
voiceapi
Package voiceapi adapts the versioned voice WebSocket protocol to a coordinator.
|
Package voiceapi adapts the versioned voice WebSocket protocol to a coordinator. |
|
voicecodec
Package voicecodec provides the portable audio codecs used by voice.v1.
|
Package voicecodec provides the portable audio codecs used by voice.v1. |
|
protocol
|
|
|
memory/package/v1
Package memorypackagev1 publishes the immutable .kmemory v1 wire contract.
|
Package memorypackagev1 publishes the immutable .kmemory v1 wire contract. |