Crate Index
Kairox is a Cargo workspace with fourteen crates plus a Tauri app crate. This page is the at-a-glance map: one row per crate, what it owns, the types you will see most often, and what depends on it. For the architectural reasoning behind the split, see Architecture.
The dependency rule
Read arrows below as "depends on":
agent-core has no workspace dependencies.
Domain crates may depend on agent-core and lower-level protocol/model crates.
agent-runtime composes the domain crates.
agent-tui, agent-gui-tauri, agent-eval, and agent-sdk compose the runtime.Domain crates do not know about the runtime or consumer crates. Consumer crates may depend on runtime and the domain crates they need to wire storage, config, or IPC.
Domain crates
agent-core
| What | Detail |
|---|---|
| Repo path | crates/agent-core |
| Purpose | Domain types, events, the AppFacade and AutonomousFacade traits, build-info plumbing, trajectory DTOs, autonomous task types, and advisor review types. |
| Key types | AppFacade, AutonomousFacade, EventPayload, DomainEvent, SessionId, TaskSnapshot, BuildInfo, TrajectoryId, AutonomousTaskId, AdvisorMode |
| Depended on by | agent-config, agent-eval, agent-gui-tauri, agent-mcp, agent-memory, agent-models, agent-runtime, agent-sdk, agent-store, agent-tools, agent-tui |
agent-core is intentionally small. It does not know how to persist events, how to call a model, or how to run a tool — it only defines the contracts. The AppFacade trait in particular is the single seam between UIs and the runtime, and the EventPayload enum is the single seam between the runtime and anything that wants to observe what is happening.
agent-store
| What | Detail |
|---|---|
| Repo path | crates/agent-store |
| Purpose | SQLite-backed event store, metadata tables, and trajectory persistence. Single source of truth for sessions. |
| Key types | EventStore (trait), SqliteEventStore, SessionMeta, TrajectoryStore, SqliteTrajectoryStore |
| Depended on by | agent-runtime, agent-eval, agent-tui, agent-gui-tauri, agent-sdk |
Event sourcing lives here. The event stream is append-only; nothing in agent-store mutates an event after it is appended. Replays for projections (like the GUI's task panel) read events back; archive flips a metadata flag. The same crate also stores task-scoped trajectory steps and can export them as JSON for replay, debugging, and eval.
agent-memory
| What | Detail |
|---|---|
| Repo path | crates/agent-memory |
| Purpose | Memory store, <memory> marker extraction, context assembly under a token budget, image pruning, and compaction. |
| Key types | MemoryStore (trait), SqliteMemoryStore, ContextAssembler, ContextCompactor, ImagePruningStrategy |
| Depended on by | agent-runtime, agent-eval, agent-tui, agent-gui-tauri, agent-sdk |
The extract_memory_markers function in this crate is where the <memory scope="..."> protocol meets the runtime. The context assembler uses tiktoken-rs for token accounting; the compactor turns the oldest tier of history into a single summary message when the budget is tight. See Memory & Context.
agent-models
| What | Detail |
|---|---|
| Repo path | crates/agent-models |
| Purpose | LLM provider clients, the streaming ModelClient trait, and the ModelRouter multiplexer. |
| Key types | ModelClient, ModelRouter, ModelRegistry, ProfileDef |
| Depended on by | agent-config, agent-memory, agent-runtime, agent-eval, agent-tui, agent-gui-tauri, agent-sdk |
One file per provider (Anthropic, OpenAI-compatible, Ollama, Fake). The ModelRegistry holds curated context-window and capability metadata; the router picks the right client for a session's active profile and forwards stream chunks back through ModelTokenDelta and AssistantMessageCompleted events.
agent-tools
| What | Detail |
|---|---|
| Repo path | crates/agent-tools |
| Purpose | The Tool trait, the ToolRegistry, the orthogonal Approval × Sandbox PolicyEngine, and the built-in tools. |
| Key types | Tool, ToolRegistry, PolicyEngine, ApprovalPolicy, SandboxPolicy, PolicyDecision, PolicyRisk, ApprovalReason, ShellExecTool, PatchApplyTool, RipgrepSearchTool, BrowserTool, BrowserBatchTool, ComputerUseTool |
| Depended on by | agent-runtime, agent-eval, agent-tui, agent-gui-tauri, agent-sdk |
Built-in tools: shell.exec, fs.read, fs.write, fs.list, patch.apply, search.ripgrep, monitor.start, monitor.list, monitor.stop, browser.action, browser.batch, and computer.use. Dynamic tool providers register additional tools at runtime: McpToolAdapter for MCP servers, LspToolProvider for LSP servers, and DapToolProvider for DAP servers. PolicyEngine::decide(PolicyRisk) returns a PolicyDecision of Allowed, DeniedBySandbox { reason }, or NeedsApproval { reason }; the runtime turns the latter into permission events. The legacy single-axis PermissionMode enum was removed end-to-end in v0.31.0. See Permissions & Tools.
agent-mcp
| What | Detail |
|---|---|
| Repo path | crates/agent-mcp |
| Purpose | MCP client, transports (stdio + SSE + Streamable HTTP), lifecycle state machine, health checks, protocol types, marketplace catalog. |
| Key types | McpClient, Transport, StdioTransport, SseTransport, StreamableHttpTransport, ServerLifecycle, McpToolAdapter, CatalogEntry |
| Depended on by | agent-config, agent-tools, agent-runtime, agent-tui, agent-gui-tauri, agent-sdk |
McpToolAdapter wraps an MCP-exposed tool in the Tool trait so the runtime treats it like a built-in. The marketplace catalog is pluggable (built-in static list + remote CatalogSource). See Extensibility.
agent-lsp
| What | Detail |
|---|---|
| Repo path | crates/agent-lsp |
| Purpose | LSP and DAP client implementations with JSON-RPC transport, server lifecycle, and code intelligence / debugger support. |
| Key types | LspClient, DapClient, LspServerDef, DapServerDef, LspServerLifecycle, DapServerLifecycle, ServerStatus |
| Depended on by | agent-config, agent-tools, agent-runtime, agent-sdk |
LSP integration provides go-to-definition, references, completions, and diagnostics by managing language server processes. DAP integration supports debugger launch/attach workflows. Both register dynamic tools via their respective tool providers so the agent can use code intelligence as part of its workflow.
agent-skills
| What | Detail |
|---|---|
| Repo path | crates/agent-skills |
| Purpose | Native skills system. Parses markdown skills with YAML frontmatter into SkillDefs and serves them via a scoped registry. |
| Key types | SkillRegistry, SkillDef, SkillFrontmatter, SkillScope |
| Depended on by | agent-runtime, agent-tui, agent-gui-tauri, agent-sdk |
Discovery is filesystem-driven: ~/.kairox/skills/, .kairox/skills/, plus any directories declared in config. Workspace skills override user skills; session skills override both.
agent-plugins
| What | Detail |
|---|---|
| Repo path | crates/agent-plugins |
| Purpose | Parses plugin manifests and exposes flat inventories of skills, tools, hooks, and MCP server declarations. |
| Key types | PluginManifest, plugin inventory helpers |
| Depended on by | agent-runtime, agent-sdk |
A plugin packages multiple contributions in a single install. The runtime routes each contribution to its owning crate (skill → SkillRegistry, tool → ToolRegistry, MCP server → McpServerManager, hook → runtime hook registry).
agent-config
| What | Detail |
|---|---|
| Repo path | crates/agent-config |
| Purpose | TOML config parsing, profile discovery, .kairox/ discovery, advisor policy, instructions, skill/MCP config wiring. |
| Key types | ProfileDef, McpServerConfig, ContextSettings, AdvisorConfig, build_router(...) |
| Depended on by | agent-runtime, agent-eval, agent-tui, agent-gui-tauri, agent-sdk |
The runtime calls build_router(...) at boot to get a configured ModelRouter plus the rest of the static config. Discovery walks up five parents from the cwd looking for .kairox/config.toml, then falls back to ~/.kairox/config.toml, then built-in defaults. See Configuration.
Composition crate
agent-runtime
| What | Detail |
|---|---|
| Repo path | crates/agent-runtime |
| Purpose | The agent loop, session actor, context budgets, compaction, model switching, agent strategies, DAG execution, advisor review, autonomous checkpoints, trajectory capture, and MCP lifecycle. |
| Key types | LocalRuntime<S, M>, DagExecutor, AgentStrategy, McpServerManager, advisor::review_tool_calls, autonomous controller and session actor types |
| Depended on by | agent-tui, agent-gui-tauri, agent-eval, agent-sdk |
LocalRuntime<S, M> is generic over its event store S and model client M. Production wires SqliteEventStore and a real ModelRouter; tests wire :memory: SQLite and a FakeModelClient. The session actor (PRs #531, #532, #533) serializes turns, model switches, and compaction against a single session. The same runtime now records trajectories, can review tool calls through the advisor layer, and exposes autonomous task control through facade methods. See Runtime & Sessions.
Consumer crates
agent-tui
| What | Detail |
|---|---|
| Repo path | crates/agent-tui |
| Purpose | Terminal UI built on ratatui. Subscribes to runtime events and renders chat, trace, sessions, MCP status. |
| Key types | App (top-level), individual screen modules |
| Depended on by | The kairox binary. |
The TUI is a thin shell over AppFacade. State is rebuilt from events on every render; there is no per-session in-memory cache that has to be hydrated.
agent-gui-tauri
| What | Detail |
|---|---|
| Repo path | apps/agent-gui/src-tauri |
| Purpose | Tauri command surface for the GUI. Exposes the runtime to the Vue frontend over IPC and emits typed events back. |
| Key types | #[tauri::command] handlers in commands.rs, type bridge in specta.rs |
| Depended on by | The Tauri build of the desktop app. |
The Vue frontend (apps/agent-gui/src) consumes generated TypeScript from apps/agent-gui/src/generated/{commands,events}.ts. Those files are regenerated by just gen-types after every EventPayload or command signature change — they are not edited by hand.
agent-sdk
| What | Detail |
|---|---|
| Repo path | crates/agent-sdk |
| Purpose | Embeddable SDK exposing the Kairox runtime as a programmatic API for external harnesses, CI/CD pipelines, and custom UIs. |
| Key types | KairoxSdk, SdkBuilder, SdkSession, MessageStream, StreamEvent, CollectedResponse, SdkHook trait, HookAction, SdkConfig |
| Depended on by | External consumers that embed the Kairox runtime. |
The SDK wraps LocalRuntime and exposes a builder pattern for configuration. Sessions produce a MessageStream of StreamEvent values that callers can consume asynchronously, or collect into a CollectedResponse. The SdkHook trait lets callers intercept approval and sandbox decisions programmatically.
Evaluation crate
agent-eval
| What | Detail |
|---|---|
| Repo path | crates/agent-eval |
| Purpose | The kairox-eval CLI. Headless evaluation harness — runs JSONL scenarios against a configured runtime and collects metrics. |
| Key types | EvalHarness, EvalScenario, EvalExpectation, EvalRunOptions, EvalResult, EvalSummary, EvalReport |
| Depended on by | Standalone binary. |
Eval depends on the runtime and the domain crates the same way the GUI does, but emits machine-readable output instead of pixels. It supports scenario listing, tag filters, fail-fast runs, JSONL results, summary JSON, combined report JSON, and expectation checks for required/forbidden events, tool counts, failures, elapsed time, and context-token budgets.
At a glance
| Crate | Lines of API surface | Stability |
|---|---|---|
agent-core | Small | The facade and EventPayload are versioned conservatively. Additions are non-breaking; renames go through deprecation cycles. |
agent-store | Small | Stable. Schema migrations are explicit and tested in crates/agent-store/tests. |
agent-memory | Medium | Memory protocol is stable; compaction internals evolve. |
agent-models | Medium | Provider clients evolve as upstreams add features. |
agent-tools | Small | Built-in tool set is intentionally fixed (see Permissions & Tools). |
agent-mcp | Medium | Tracks upstream MCP spec; transports stable. |
agent-skills | Small | Frontmatter is stable; discovery rules can grow. |
agent-plugins | Small | Manifest is stable; contribution kinds can grow. |
agent-config | Medium | TOML schema additions are non-breaking; removals trigger a migration warning. |
agent-runtime | Large | Internal types refactor freely; observable behavior (events, facade) is stable. |
agent-tui | Medium | UI changes are not API; bindings are stable. |
agent-gui-tauri | Medium | Tauri commands are an API contract with the Vue frontend; changes go through just gen-types. |
agent-eval | Small | CLI flags are stable; harness is evolving. |
agent-sdk | Small | Public API is new and evolving; builder + stream patterns are stable. |
What this page does not cover
This page lists the crates and their roles. It does not explain how a turn flows through them (Runtime & Sessions), what the layered architecture is (Architecture), or what the configuration schema looks like (Configuration).