kodacode

module
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 8, 2026 License: AGPL-3.0

README

KodaCode

Turns AI coding from suggestion generator into work executor.

Go Release Homebrew Docs

KodaCode is an open-source, terminal-native coding agent built for trustworthy software delivery. It keeps orchestration, permissions, tool execution, prompt assembly, and replayable session state in runtime code and stored events instead of hidden prompt behavior.

Install

# Homebrew
brew tap sageil/tap && brew install --cask kodacode

# Quick install
curl -fsSL https://raw.githubusercontent.com/sageil/kodacode/main/install.sh | sh

# Go
go install github.com/sageil/kodacode/cmd/kodacode@latest

See the installation guide for setup details.

Quick Start

Run KodaCode in the repository you want to work in:

kodacode

Inside the TUI:

  1. Use /connect to configure a provider.
  2. Use /model to choose a model route, such as openai/gpt-5.
  3. Use /init to create workspace instructions.
  4. Ask for one concrete task.

For a full first-session walkthrough, see the Quick Start. For provider IDs and route behavior, see Model Routing.

How It Works

KodaCode roots a session at your current workspace. Relative file access starts there, while external paths, network access, and sensitive commands go through explicit runtime-owned approval gates.

Use builder when the task is clear and contained. Use engineer when the task is broad, risky, architectural, or needs an approved plan before edits.

Example prompt:

Build a calculator that estimates monthly payment, total interest, and affordability range.

Acceptance criteria:

- Inputs: home price, down payment, interest rate, amortization years, property tax, insurance, condo fees, gross monthly income, monthly debts.
- Outputs: loan amount, estimated monthly principal + interest, total monthly housing cost, debt-to-income ratio, and affordability status.
- Use standard fixed-rate mortgage amortization math.
- Validate invalid inputs clearly.
- Add focused tests for payment calculation, DTI calculation, and edge cases.
- Do not use fake values or hardcoded backend state.
- Run the relevant test suite before finishing.

For a plan-first flow, select the engineer agent in the TUI and ask:

Before editing, inspect the app structure, propose a short implementation plan,
and wait for approval before making code changes.

Core Features

Agents

  • builder: default project-sandboxed coding agent
  • engineer: structured planning and workflow task tracking
  • reviewer: read-only review of current changes
  • planner: read-only repository analysis and implementation planning

See Agents for custom agent definitions and tool policy behavior.

Layouts

KodaCode has two TUI layouts for different working styles:

  • Shell layout is the default single-plane workflow. It keeps the transcript, tool activity, diffs, and final responses in one continuous terminal surface.
  • Classic layout keeps a persistent right-side inspector with Details, Tools, and Tasks tabs. It is useful when you want the main transcript and structured tool/task state visible at the same time.

Switch layouts from the TUI with Ctrl+L, or set a default in ~/.config/kodacode/config.yaml with tui.layout: shell or tui.layout: classic. See TUI Layouts for details.

KodaCode shell layout showing a full-width transcript with inline tool and diff output KodaCode classic layout showing the transcript beside Details, Tools, and Tasks inspector tabs

Useful Commands

  • /connect: configure a provider
  • /model: choose the active model
  • /init: create workspace instructions
  • /timeline: branch from an earlier completed turn or navigate related branches
  • /trace: inspect what happened in a turn
  • /cost: inspect spend and token savings
  • Ctrl+W: list or select a runtime workflow such as delivery, debug, review, or explore

See Slash Commands for the full command surface.

One-Shot CLI

kodacode "summarize this repository"
kodacode --resume "continue the previous refactor"
kodacode --add-dir ../shared "inspect both repos before editing"
kodacode --skill migration "add the schema change and focused tests"
kodacode --workflow delivery "implement this change and verify it"

Documentation

Full documentation, configuration reference, and guides are available at kodacode.dev.

License

AGPL-3.0

Directories

Path Synopsis
cmd
kodacode command
Package main wires the kodacode CLI and terminal application entrypoints.
 Package main wires the kodacode CLI and terminal application entrypoints.
internal
agent
Package agent loads agent definitions, catalogs, and built-in agent behavior.
 Package agent loads agent definitions, catalogs, and built-in agent behavior.
app
Package app orchestrates sessions, turns, tools, and provider execution.
 Package app orchestrates sessions, turns, tools, and provider execution.
bootstrap
Package bootstrap builds application defaults used during startup.
 Package bootstrap builds application defaults used during startup.
codeintel
Package codeintel connects tool-facing code-intelligence operations to LSP servers.
 Package codeintel connects tool-facing code-intelligence operations to LSP servers.
configdir
Package configdir resolves kodacode user configuration directories.
 Package configdir resolves kodacode user configuration directories.
engine
Package engine defines the model-facing execution interface used by runtimes.
 Package engine defines the model-facing execution interface used by runtimes.
events
Package events defines durable session events, replay storage, and projection.
 Package events defines durable session events, replay storage, and projection.
filemutation
Package filemutation provides atomic file writes and per-file mutation locks.
 Package filemutation provides atomic file writes and per-file mutation locks.
lsp
Package lsp manages language server discovery, startup, and query execution.
 Package lsp manages language server discovery, startup, and query execution.
lspedit
Package lspedit applies LSP text edits to document content.
 Package lspedit applies LSP text edits to document content.
mcp
Package mcp manages MCP transports and their runtime registration.
 Package mcp manages MCP transports and their runtime registration.
observability
Package observability provides structured logging and retention helpers.
 Package observability provides structured logging and retention helpers.
permissionpolicy
Package permissionpolicy matches declarative permission rules against requests.
 Package permissionpolicy matches declarative permission rules against requests.
prompt
Package prompt compiles prompt fragments into provider-ready instructions.
 Package prompt compiles prompt fragments into provider-ready instructions.
provider
Package provider integrates model providers and normalizes their request flows.
 Package provider integrates model providers and normalizes their request flows.
provider/anthropicreasoning
Package anthropicreasoning provides Anthropic reasoning capability helpers.
 Package anthropicreasoning provides Anthropic reasoning capability helpers.
provider/deepseekreasoning
Package deepseekreasoning provides DeepSeek reasoning capability helpers.
 Package deepseekreasoning provides DeepSeek reasoning capability helpers.
provider/googlereasoning
Package googlereasoning provides Google Gemini reasoning capability helpers.
 Package googlereasoning provides Google Gemini reasoning capability helpers.
provider/mistralreasoning
Package mistralreasoning provides Mistral reasoning capability helpers.
 Package mistralreasoning provides Mistral reasoning capability helpers.
provider/openaicache
Package openaicache provides OpenAI prompt-cache retention and key helpers.
 Package openaicache provides OpenAI prompt-cache retention and key helpers.
provider/openaireasoning
Package openaireasoning provides OpenAI-family reasoning effort helpers.
 Package openaireasoning provides OpenAI-family reasoning effort helpers.
provider/openaiurl
Package openaiurl normalizes OpenAI-compatible API base URLs.
 Package openaiurl normalizes OpenAI-compatible API base URLs.
provider/qwenreasoning
Package qwenreasoning provides Qwen reasoning capability helpers.
 Package qwenreasoning provides Qwen reasoning capability helpers.
search
Package search indexes workspaces and serves lexical and semantic search.
 Package search indexes workspaces and serves lexical and semantic search.
sessiontitle
Package sessiontitle derives concise session titles from user prompts.
 Package sessiontitle derives concise session titles from user prompts.
skill
Package skill loads, parses, and indexes user and project skills.
 Package skill loads, parses, and indexes user and project skills.
textdiff
Package textdiff renders compact previews of text mutations.
 Package textdiff renders compact previews of text mutations.
textutil
Package textutil provides shared text accumulation and truncation helpers.
 Package textutil provides shared text accumulation and truncation helpers.
tool
Package tool defines tool contracts and built-in tool implementations.
 Package tool defines tool contracts and built-in tool implementations.
tui
Package tui renders the terminal interface and maps runtime state to views.
 Package tui renders the terminal interface and maps runtime state to views.
tui/theme
Package theme loads, catalogs, and applies terminal UI themes.
 Package theme loads, catalogs, and applies terminal UI themes.
websearch
Package websearch provides web search backend implementations.
 Package websearch provides web search backend implementations.
workflow
Package workflow loads, validates, and catalogs workflow definitions.
 Package workflow loads, validates, and catalogs workflow definitions.
workspace
Package workspace defines workspace scope, grants, and path authorization.
 Package workspace defines workspace scope, grants, and path authorization.
workspaceedit
Package workspaceedit applies LSP workspace edits to files.
 Package workspaceedit applies LSP workspace edits to files.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.