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
Remote File Management
Open a session's file browser to manage files on the machine running Koder:
- Select a folder (or Project root) and use Upload, or drop local files onto a folder. Multiple files are supported, up to 256 MB each.
- Drag a file or folder onto another folder or Project root to move it. Rename / move also accepts a project-relative destination path.
- Use New folder to organize files, and Delete to remove the selected file or folder. Deletion requires confirmation and is permanent; deleting a folder removes its contents too.
Uploads and moves never overwrite existing names. Failed uploads are cleaned up without publishing partial files. Operations stay inside the session's project folder and use the server account's filesystem permissions; these are human UI actions, separate from the agent's sandbox permissions. Moves across different filesystems are not supported.
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. A session's own access (its project folder, home, and session folders) overrides shared folders: a project inside a read-only shared /storage stays writable, and a session folder overrides a shared one at the same or a deeper path. Within each, the most specific path wins.
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
Upgrading A Running Service
Send Koder SIGUSR2 to make it exit once it is idle. Koder waits until no
chat is running, queued or waiting for approval and no exec session is running,
then shuts down cleanly and exits 0. A systemd unit with Restart=on-failure
then stays stopped.
scripts/koder-upgrade NEW_BINARY [TARGET] [UNIT] upgrades a systemd user
service using that signal:
- It checks that the new binary runs
version. - It sends
SIGUSR2and waits for the service to stop. - It keeps the old binary as
TARGET.prev, moves the new one into place and starts the service.
TARGET defaults to ~/.local/bin/koder and UNIT to koder.service.
To upgrade by dropping a binary at ~/.local/bin/koder.new:
- Copy
scripts/koder-upgradeto~/.local/bin. - Copy
scripts/systemd/koder-upgrade.pathandkoder-upgrade.serviceto~/.config/systemd/user. - Run
systemctl --user enable --now koder-upgrade.path.
After that, scp koder host:.local/bin/koder.new is enough. A binary that does
not run is renamed koder.new.rejected.
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. |
|
claudeapp
Package claudeapp implements the Claude Code stream-json transport: user messages and control requests go to stdin, and stdout carries the conversation stream plus control requests from the CLI, such as calls to an SDK-hosted MCP server.
|
Package claudeapp implements the Claude Code stream-json transport: user messages and control requests go to stdin, and stdout carries the conversation stream plus control requests from the CLI, such as calls to an SDK-hosted MCP server. |
|
claudedriver
Package claudedriver runs Koder chat turns through Claude Code.
|
Package claudedriver runs Koder chat turns through Claude Code. |
|
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. |
|
fsutil
Package fsutil holds small filesystem helpers shared across koder.
|
Package fsutil holds small filesystem helpers shared across koder. |
|
memory
Package memory keeps notes the model carries between chats as markdown files: one file per memory, in a global folder (the user, their machine, preferences that hold everywhere) and a private folder per project.
|
Package memory keeps notes the model carries between chats as markdown files: one file per memory, in a global folder (the user, their machine, preferences that hold everywhere) and a private folder per project. |
|
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. |
|
redact
Package redact decides which values must be hidden from debug traces.
|
Package redact decides which values must be hidden from debug traces. |
|
textutil
Package textutil holds small string helpers shared across koder.
|
Package textutil holds small string helpers shared across koder. |
|
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 lets the model read and keep notes across chats.
|
Package memorytool lets the model read and keep notes across chats. |
|
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. |