Koder

Koder is an experimental, open-source AI coding assistant for the terminal. It combines a streaming TUI, persistent local sessions, repository-aware tools, extensible skills, MCP integrations, sandbox-aware permissions, and multi-agent workflows in one Python runtime.

Status: Alpha. Koder is a learning-focused project for exploring agentic coding systems. Expect rapid iteration and occasional sharp edges.

Start Here

uv tool install koder
export KODER_API_KEY="your-api-key"
export KODER_MODEL="gpt-4o"
koder

Prefer a provider-specific key or subscription login? Jump to Model Configuration.

Why Koder

Koder is designed for developers who want a local-first coding agent they can inspect, extend, and run across model providers without changing their workflow.

• Bring your own model: OpenAI, Anthropic, Google/Gemini, GitHub Copilot, Azure, OAuth-backed subscriptions, OpenRouter, and 100+ LiteLLM providers.
• Stay in the terminal: use slash commands, file mentions, shell mode, history search, live usage output, and optional voice dictation.
• Keep runtime state local: sessions, transcripts, memories, task records, settings, skills, agents, and team state live under Koder-owned local paths. Model requests still go to the provider you configure.
• Extend the runtime: add project skills, user skills, plugins, MCP servers, channels, and Magic Docs.
• Delegate carefully: run background subagents and local teams while the main session stays responsible for integration.
• Study the system: the Python codebase is organized to make agent scheduling, provider routing, permissions, tools, and TUI behavior easy to trace.

How It Fits

Koder is in the same broad family as terminal-first and open-source AI coding agents. Its emphasis is different:

If you care about...	Koder emphasizes
Provider choice	Universal KODER_* variables, provider-specific keys, OAuth-backed subscriptions, custom base URLs, and LiteLLM provider routing.
Terminal ergonomics	A persistent Rich TUI with slash commands, shell mode, file mentions, usage/cost output, voice input, and resume.
Local inspectability	SQLite sessions, local memory, local settings, local tokens, and documented privacy boundaries.
Extension experiments	Skills, verifier skills, plugins, MCP servers, channels, Magic Docs, and project instructions.
Multi-agent workflows	Background subagents, local teams, tmux teammates, mailbox/task records, and team memory.
Safety research	Permission rules, managed settings, sandbox policy, backend diagnostics, and explicit local/remote data boundaries.

Highlights

Area	What You Get
Interactive TUI	Streaming output, slash completion, shell mode, file mentions, status line, reverse history search, and multi-line prompts.
Model routing	Universal KODER_* variables, provider-specific keys, custom base URLs, reasoning effort, and subscription-backed OAuth providers.
Durable context	SQLite sessions, named sessions, resume, export, compaction, rewind, thinkback, local memories, and AutoDream consolidation.
Coding tools	File operations, search, shell execution, git helpers, notebooks, web fetch/search, todos, and local code intelligence.
Workflows	Review, security review, advisor, planning, commit readiness, PR comments, GitHub Actions setup, release notes, and verification summaries.
Agents and teams	Project/user agents, task_delegate, /fork, /peers, in-process teammates, tmux teammates, mailbox routing, tasks, and team memory.
Extensions	Skills, verifier skills, plugins, MCP servers, channels, and Magic Docs.
Safety controls	Permission rules, sandbox policy, managed settings, workspace roots, privacy diagnostics, and local storage boundaries.

Installation

Install the published CLI with uv:

uv tool install koder

Or use pip:

pip install koder

For local development from this repository:

git clone https://github.com/feiskyer/koder.git
cd koder
uv sync
uv run koder

Requirements: Python 3.10 or newer and a model provider credential or subscription login.

Quick Start

Set a model credential and start the interactive TUI:

export KODER_API_KEY="your-api-key"
export KODER_MODEL="gpt-4o"
koder

Run a single prompt from the shell:

koder "summarize the current repository"

Use a named session when you want durable context for a project or feature:

koder -s billing-refactor
koder -s billing-refactor "continue the failing test investigation"
koder --resume

Good first commands inside the TUI:

/onboarding
/status
/model
/files
/permissions
/help

Good first prompts:

Inspect this repository and explain the test command.
Find the smallest safe fix for the failing test, then run the focused test.
Review the current diff for correctness and missing verification.

Common Usage

Task	Command
Open the TUI	koder
Run one prompt	koder "fix the failing test"
Print script-friendly output	koder --print "summarize"
Use a named session	koder -s my-project
Resume previous work	koder --resume or koder --continue
Inspect runtime state	/status, /summary, /stats, /doctor
Inspect context	/files, /context, /ctx_viz
Review changes	/diff, /review, /security-review
Check usage and cost	/usage, /cost
Manage agents and teams	/agents, /fork, /peers, /tasks
Manage extensions	/skills, /plugin, /mcp, /channels
Manage permissions	/permissions, /sandbox, /add-dir

See the Command Reference for the complete slash-command catalog.

Trust Boundaries

Koder is local-first, not offline-only:

• Koder stores product state under ~/.koder/ and project .koder/ paths by default.
• Koder does not upload sessions to a Koder-hosted service.
• Prompts, selected context, and tool results needed for a turn are sent to the model provider you configure.
• MCP servers, plugins, shell commands, and teammate processes can access whatever their local permissions allow unless constrained by Koder policy and sandbox settings.
• OAuth tokens are stored under ~/.koder/tokens/; avoid committing secrets into project files.

Inspect the current boundary with:

/privacy-settings
/permissions
/sandbox status
/files
/context

Model Configuration

Koder resolves configuration in this order:

1. CLI arguments
2. Environment variables
3. ~/.koder/config.yaml
4. Built-in defaults

Universal environment variables work across providers:

Variable	Purpose	Example
KODER_API_KEY	Universal API key	sk-...
KODER_MODEL	Active model	gpt-4o, claude-opus-4-20250514
KODER_BASE_URL	Custom OpenAI-compatible endpoint	http://localhost:8080/v1
KODER_REASONING_EFFORT	Reasoning effort	low, medium, high
KODER_REASONING_DISPLAY	Reasoning display mode	off, summary, full

Provider-specific examples:

OPENAI_API_KEY="sk-..." KODER_MODEL="gpt-4o" koder
ANTHROPIC_API_KEY="..." KODER_MODEL="claude-opus-4-20250514" koder
GOOGLE_API_KEY="..." KODER_MODEL="gemini/gemini-2.5-pro" koder
KODER_BASE_URL="http://localhost:8080/v1" KODER_MODEL="openai/local-model" koder

Subscription-backed providers use local OAuth token stores:

koder auth login google
koder auth login claude
koder auth login chatgpt
koder auth login antigravity
koder auth list

After login, select an OAuth-backed model with its provider prefix:

KODER_MODEL="google/gemini-3-pro-preview" koder
KODER_MODEL="claude/claude-opus-4-5-20250514" koder
KODER_MODEL="chatgpt/gpt-5.2" koder

OAuth tokens and cached model lists are stored under ~/.koder/tokens/.

Configuration File

Persistent defaults live in ~/.koder/config.yaml:

model:
  name: "gpt-4o"
  provider: "openai"
  reasoning_effort: null

cli:
  session: null
  stream: true

mcp_servers: []

voice:
  enabled: false
  provider: null
  model: null

harness:
  reasoning_display: "off"

Useful configuration commands:

koder config show
koder config edit
koder config export ~/koder-settings.json
koder config import ~/koder-settings.json --dry-run

See the Configuration Guide for provider setup, OAuth, settings bundles, managed settings, MCP configuration, and voice routing.

Extending Koder

Koder can be extended at the project, user, and plugin levels.

Skills

Skills are local instruction bundles loaded on demand:

.koder/skills/api-review/SKILL.md
~/.koder/skills/personal-style/SKILL.md

---
name: api-review
description: Review API changes for compatibility and error handling
allowed_tools:
  - read_file
  - grep_search
---

Review public API changes for request shape, response shape, status codes, and migration notes.

Inspect skills with /skills. Create verifier skills with /init-verifiers.

MCP Servers

MCP servers add external tools to the runtime:

koder mcp add filesystem "python -m mcp.server.filesystem" --scope project
koder mcp add api --transport http --url http://localhost:8000
koder mcp list

Plugins And Channels

Plugins can contribute skills, commands, MCP servers, channels, and dependencies:

koder plugin install ./my-plugin --scope project
koder plugin list
koder --channels server:my-channel
koder --channels plugin:team-chat@local
koder /channels

See Skills, Plugins, and MCP for the full extension model.

Architecture

koder_agent/
├── agentic/        # Agent creation, hooks, guardrails, approvals
├── auth/           # OAuth providers, token storage, provider-specific routing
├── cli.py          # Main CLI entry point
├── config/         # YAML, environment, and settings management
├── core/           # Scheduler, sessions, streaming, security, TUI prompt
├── harness/        # Runtime commands, plugins, memory, permissions, teams, UI scaffolding
├── mcp/            # Model Context Protocol integration
├── providers/      # Provider routing metadata
├── tools/          # Tool implementations
└── utils/          # Client setup, prompts, sessions, model info, terminal theme

Runtime flow:

1. cli.py parses arguments and builds a runtime request.
2. HarnessRuntime loads permissions and dispatches interactive, prompt, and subcommand modes.
3. Session flow wires context, hooks, plugins, agents, slash commands, and scheduler execution.
4. AgentScheduler streams model execution and usage tracking.
5. Tool and permission layers validate file, shell, MCP, skill, and teammate operations.
6. EnhancedSQLiteSession persists transcripts and session metadata in ~/.koder/koder.db.

Development

Set up the repository:

uv sync
uv run koder

Code quality and tests:

uv run black . && uv run ruff format && uv run ruff check --fix
uv run pytest

Focused test examples:

uv run pytest tests/test_file_tools.py
uv run pytest -v -k "test_name"

Security And Privacy

• API keys should live in environment variables or local user config, not project files.
• OAuth tokens and cached provider model lists are stored under ~/.koder/tokens/.
• Sessions, transcripts, memories, tasks, agents, and teams are stored locally under ~/.koder/ and project .koder/ paths.
• Koder does not upload sessions to a Koder-hosted service. Model requests still go to the provider you configure.
• Shell, file, MCP, and teammate operations are mediated by local permission and sandbox policy. Foreground shell commands can use a real sandbox backend when /sandbox status reports that backend as available.

Use these commands to inspect boundaries:

/privacy-settings
/permissions
/sandbox
/managed-settings
/files
/context

See Sandbox Guide and Permissions and Privacy for details.

Documentation

• Feature Guide - topic map for Koder's main user-facing capabilities
• Getting Started - first install, provider setup, and a safe first session
• Interactive TUI - prompt controls, slash commands, mentions, shell mode, and voice input
• Configuration Guide - config files, environment variables, providers, OAuth, and settings bundles
• Sessions and Memory - named sessions, resume, compaction, rewind, memory, and local storage
• Agents and Teams - background subagents, project agents, teams, teammate modes, and team memory
• Workflows - review, planning, Git, GitHub, release, and verification workflows
• Skills, Plugins, and MCP - extending Koder with skills, plugins, MCP servers, channels, and Magic Docs
• Permissions and Privacy - approvals, sandbox policy, managed settings, workspace roots, and data boundaries
• Sandbox Guide - shell sandbox backends, status fields, configuration, and troubleshooting
• Voice Mode - voice dictation setup and provider-specific notes
• Command Reference - complete slash-command catalog

Contributing

Contributions are welcome.

1. Fork the repository.
2. Create a feature branch: git checkout -b feature/amazing-feature.
3. Make a focused change with tests or validation.
4. Commit your changes: git commit -m 'Add amazing feature'.
5. Push the branch and open a pull request.

See CONTRIBUTING.md for guidelines.

License

MIT License. See LICENSE for details.