Crate koda_core 

Koda Core — the engine library for the Koda AI coding agent.

This crate contains the pure engine logic with zero terminal dependencies. It communicates exclusively through engine::EngineEvent (output) and engine::EngineCommand (input) enums.

Quick navigation

Module	What it does
agent	Agent construction and built-in agent catalog
tools	19 built-in tools (file ops, shell, search, web, memory, agents)
providers	14 LLM providers (Anthropic, OpenAI, Gemini, local, etc.)
inference	Streaming inference loop with tool execution
config	Configuration loading, agent discovery, settings
trust	Safety gates and approval modes
engine	Event/command protocol (client–engine boundary)
compact	Context compaction (summarize old messages)
memory	Persistent semantic memory (MEMORY.md)
skills	Expertise modules (prompt injection, zero LLM cost)
db	SQLite persistence (sessions, history, file ownership)

Architecture

┌───────────────┐  EngineEvent   ┌─────────────────┐
│   koda-cli    │ ←───────────── │    koda-core    │
│  (TUI/REPL)   │ ─────────────→ │   (engine lib)  │
└───────────────┘  EngineCommand └────────┬────────┘
                                          │
                                   ┌──────┴──────┐
                                   │  providers  │
                                   │ (LLM APIs)  │
                                   └─────────────┘

See DESIGN.md in the repository root for the full architectural rationale.

Modules

agent

Sub-agent configuration, discovery, and invocation. KodaAgent — shared, immutable agent resources.

bash_path_lint

Heuristic path-escape detection for bash commands. Bash path lint — detect commands that escape the project root.

bash_safety

Bash command safety classification — ReadOnly, LocalMutation, Destructive. Bash command safety classification.

bg_agent

Background sub-agent registry — tracks and drains async agent results. Background sub-agent registry.

compact

Context compaction — summarise old messages to reclaim token budget. Session compaction — summarize old messages to reclaim context.

config

Global configuration: provider, model, model settings, CLI flags. Configuration loading for agents and global settings.

context_analysis

Context analysis — per-tool token breakdown and duplicate detection. Context analysis — per-tool token breakdown and duplicate detection.

db

SQLite persistence layer — sessions, messages, usage tracking. SQLite persistence layer.

engine

Engine protocol: EngineEvent / EngineCommand enums. Engine module — the protocol boundary between Koda’s core and any client.

file_tracker

File lifecycle tracker — tracks files created by Koda per session (#465). File lifecycle tracker — tracks files created by Koda during a session.

git

Git context injection — branch, staged/unstaged diffs, recent commits. Git integration for context injection.

inference

The main inference loop — send messages, stream responses, dispatch tools. LLM inference loop with streaming, tool execution, and sub-agent delegation.

inference_helpers

Shared helpers used by the inference loop. Helper functions for inference — context estimation, message assembly, error classification.

keystore

Credential storage — keys.toml with env var fallback. Secure API key storage (#693).

last_provider

Last-used provider recall (stored in SQLite KV store, not a config file). Last-used provider recall (#693).

loop_guard

Loop detection — catches runaway repeated tool calls. Loop detection for the inference loop.

mcp

MCP client — connect to external MCP servers (#662). MCP client — connect to external MCP servers (#662).

memory

Project memory — MEMORY.md / CLAUDE.md read/write. Semantic memory: project context injected into the system prompt.

microcompact

Microcompact — lightweight tool result aging without full compaction. Microcompact — lightweight tool result aging without full compaction.

model_alias

Hardcoded model aliases for stable, cross-provider model selection. Hardcoded model aliases for stable, cross-provider model selection.

model_context

Hardcoded context-window lookup table (fallback when API doesn’t report). Model context window lookup.

output_caps

Context-scaled output caps for tool results. Centralized tool output caps, scaled to the model’s context window.

persistence

Persistence trait — the database contract. Persistence trait — the storage contract for koda.

preview

Diff preview generation for file mutations. Pre-confirmation diff previews for destructive tool operations.

prompt

System prompt construction. System prompt construction.

provider_catalog

Static provider catalog: ProviderType + ProviderMeta lookup tables. Provider catalog — static metadata for every supported LLM provider.

providers

LLM provider abstraction — Anthropic, Gemini, OpenAI-compatible. LLM provider abstraction layer.

runtime_env

Thread-safe runtime environment — replaces std::env::set_var. Thread-safe runtime environment for API keys and config.

sandbox

Process sandboxing for the Bash tool (macOS seatbelt / Linux bwrap). Process sandboxing for the Bash tool — thin shim over koda_sandbox.

session

Session lifecycle — create, resume, list, delete. KodaSession — per-conversation state.

skill_scope

Skill-scoped tool filtering — hard enforcement of allowed_tools. Skill-scoped tool filtering.

skills

Skill discovery and activation (project, user, built-in). Skill discovery and loading.

sub_agent_cache

Sub-agent result caching — zero-cost retries after compaction. Sub-agent result caching.

tool_dispatch

Tool dispatch — routes tool calls from inference to the registry. Tool execution dispatch — sequential, parallel, and split-batch.

tool_normalize

Tool name normalization — maps model-emitted variants to canonical PascalCase. Tool name normalization — maps model-emitted variants to canonical PascalCase.

tools

Tool registry, definitions, execution, and path safety. Tool registry and execution engine.

truncate

Token-safe output truncation. Output truncation for display.

trust

Unified trust mode — single permission knob replacing ApprovalMode × SandboxMode. Unified trust mode — the single permission knob for Koda.

undo

Undo stack for file mutations. Undo stack for file mutations.

version

Version string and update-check helpers. Version checker — non-blocking startup check for newer crate versions.