Kairox

Kairox is a local-first AI agent workbench built with a shared Rust core, a terminal UI, and a Tauri + Vue desktop GUI.

Quick links

• Website
• Latest release
• Roadmap
• Contributing
• Security policy
• Discussions
• Code of conduct
• Release guide

Architecture

graph TD
    UI["User Interfaces"]
    TUI["TUI (ratatui)"]
    GUI["GUI (Tauri + Vue)"]
    EVAL["agent-eval (kairox-eval)"]
    SDK["agent-sdk"]
    CORE["agent-core"]
    RUNTIME["agent-runtime"]
    MODELS["agent-models"]
    TOOLS["agent-tools"]
    MCP["agent-mcp"]
    LSP["agent-lsp"]
    SKILLS["agent-skills"]
    PLUGINS["agent-plugins"]
    MEMORY["agent-memory"]
    STORE["agent-store"]
    CONFIG["agent-config"]

    UI --> TUI
    UI --> GUI
    TUI --> CORE
    GUI --> CORE
    EVAL --> CORE
    SDK --> CORE
    CORE --> RUNTIME
    RUNTIME --> MODELS
    RUNTIME --> TOOLS
    RUNTIME --> MCP
    RUNTIME --> LSP
    RUNTIME --> SKILLS
    RUNTIME --> PLUGINS
    RUNTIME --> MEMORY
    RUNTIME --> STORE
    RUNTIME --> CONFIG

Loading

Highlights

• Local-first architecture with a shared Rust core
• Two user surfaces: TUI and Tauri + Vue desktop GUI
• Context-aware runtime with per-model token budgets, compaction, mid-session model switching, and reasoning effort selection
• Structured runtime, memory, tools, MCP, skills, plugins, and persistence layers
• Real desktop and browser E2E coverage with CI, release automation, and community docs

Features

• Shared Rust core — domain types, event-sourced runtime, facade trait, typed IDs
• Memory system — durable session/user/workspace-scoped memory with <memory> marker protocol, keyword retrieval, workspace RAG, profile-scoped external KB retrieval, and context assembly
• Context management — per-model context windows, budget-driven prompt assembly, manual/automatic compaction, busy-state guards, and GUI context usage meter
• Model adapters — OpenAI, Anthropic, Ollama, and fake provider for testing, with mid-session model switching and reasoning effort selection when profiles support it
• Tool system — built-in tools (shell.exec, context-aware search.ripgrep, patch.apply, fs.read, fs.write, fs.list, monitor.start, monitor.list, monitor.stop, browser.action, browser.batch, computer.use) with orthogonal Approval × Sandbox policy control and MCP (Model Context Protocol) integration
• MCP marketplace and connectivity — built-in catalog plus remote sources with multi-source aggregation, one-click install, runtime-missing hints, GUI connectivity actions, Streamable HTTP transport support, and server diagnostics
• Skills, plugins, and instructions — native skills for reusable prompt/tool/workflow capabilities, plugin-namespaced skill discovery, plugin permission/trust/compatibility metadata, plugin settings, hook settings, and user/project instruction settings with effective-preview support
• Config discovery — TOML config with profile management, env-variable API keys, and per-project .kairox/ directory discovery
• Workspace flows — project workspace management in the GUI for organizing multiple working contexts
• TUI application — three-panel ratatui terminal UI with streaming chat, trace, permission prompts, command palette, queue controls, and settings/marketplace overlays
• GUI desktop app — Tauri 2 + Vue 3 with persistent sessions, session switching, trace visualization, memory browser, inline chat-stream permission/tool/compaction flow, per-session permission mode selection, model/agent/plugin/hook/instructions/skills settings, resizable workbench sidebars, and MCP marketplace UI
• Autonomous tasks — checkpoint-driven autonomous task management with orientation, pause/resume/cancel, and GUI settings panel
• Advisor self-reflection — configurable advisor layer that reviews tool calls before execution for safety and correctness
• Trajectory recording — automatic session trajectory capture with runtime recording and GUI trajectory viewer
• Embeddable SDK — agent-sdk crate exposing the Kairox runtime as a programmatic API for external harnesses, CI/CD pipelines, and custom UIs
• Auto-update — Tauri 2 auto-update wired to GitHub Releases for the desktop app
• Local-first architecture — designed for offline-friendly workflows and explicit permission control
• Quality gates — parallel CI with aggregation ci-success job, branch-focused Rust/Vue coverage gates, type-sync checks, cargo clippy, oxlint, Stylelint, oxfmt, commitlint, tauri-pilot desktop E2E, and live model smoke tests
• Environment automation and monitors — browser automation, batched browser actions, desktop computer-use primitives, and background shell monitors that stream stdout as session events with timeout and persistent modes
• Trajectory persistence — task-scoped trajectory DTOs and SQLite storage for ordered action/observation steps with JSON export for replay, debugging, and eval
• Evaluation harness — headless kairox-eval binary for JSONL scenarios with tag filters, list mode, fail-fast runs, expectation budgets, summaries, and combined reports
• E2E testing — Playwright frontend E2E specs, tauri-pilot real desktop scenarios, expanded TUI app-logic coverage, 13 full-stack runtime tests, dedicated MCP integration tests, live GitHub Models smoke coverage, and DAG executor / AgentStrategy / GUI component coverage

Repository layout

• crates/agent-core — shared domain types, events, IDs, projections, and application facade
• crates/agent-runtime — runtime orchestration, agent loop, DAG executor, multi-agent strategies, MCP server manager
• crates/agent-models — model client trait + OpenAI / Anthropic / Ollama / Fake adapters
• crates/agent-tools — tool registry, permission engine, built-in tools (shell.exec, fs.read/write/list, patch.apply, search.ripgrep, monitor.start/list/stop, browser.action, browser.batch, computer.use), MCP tool adapter
• crates/agent-mcp — MCP (Model Context Protocol) client, stdio + SSE + Streamable HTTP transports, server lifecycle, diagnostics, discovery cache, marketplace catalog (built-in + remote sources)
• crates/agent-lsp — LSP and DAP clients, stdio transports, and lifecycle management for code intelligence and debugging integrations
• crates/agent-skills — native skills system for reusable prompt, tool, and workflow capabilities with config-driven discovery
• crates/agent-plugins — plugin manifest and inventory parsing for plugin-provided skills, tools, hooks, and MCP servers
• crates/agent-memory — memory store, marker protocol, context assembly with tiktoken
• crates/agent-store — SQLite-backed event store, metadata tables, and trajectory store
• crates/agent-config — TOML config loading, model profile discovery, MCP server config, skills config, API key resolution, layered user/project/local .kairox/ discovery
• crates/agent-eval — headless evaluation harness (kairox-eval binary) for running JSONL scenarios with filters, expectations, summaries, reports, and metrics
• crates/agent-sdk — embeddable runtime API for external harnesses, CI/CD pipelines, and custom UIs
• crates/agent-tui — interactive ratatui terminal UI app
• apps/agent-gui — Vue 3 frontend + Tauri 2 desktop app (with auto-generated specta TypeScript bindings)

Status

Kairox is in active development (current release v0.43.0) with a fully interactive TUI and a functional GUI featuring persistent session management, task graph visualization, searchable trace timeline, structured trace export, searchable settings surfaces, memory browser, inline chat authorization/tool/compaction flow, MCP server manager, MCP marketplace, MCP connectivity actions and diagnostics, context meter, skills system, instructions settings, hook settings, plugin settings, project workspace flows, resizable workbench sidebars, per-session permission control, browser/computer-use tools, background monitors, native LSP/DAP code intelligence, and remote skill marketplace. The TUI supports CLI flags for profile and policy selection, model overlay with context-window details, monitor overlay, and remote skill search and install. Sessions persist across restarts via SQLite storage.

Streaming tool-call handling is robust for OpenAI-compatible and Anthropic providers, with JSON Schema parameters and CancellationToken support for streaming cancellation. The runtime tracks per-model context windows, assembles prompts against token budgets, supports manual and automatic context compaction, allows mid-session model switching with reasoning effort selection when profiles support it, and can create isolated git worktrees for project worktree sessions.

The GUI supports executable slash commands from the palette, file mentions that attach content for backend reads, draft persistence, task retry/cancel actions, session cancellation, error notifications, code syntax highlighting, a real-time status bar, agent attribution, N-level task tree visualization, context usage feedback, and polished accessibility/test selectors validated by tauri-pilot scenarios.

Phase 2 DAG execution with AgentStrategy enables multi-agent orchestration (planner / worker / reviewer). Agent settings can override model profile, approval/sandbox policy, skills, tool allowlists, and reasoning effort per role. Sessions execute through per-session actors (agent-runtime/src/execution_runtime/) with race-free turn-end compaction, and the runtime is split into focused modules (agent_loop, dag_executor, event_emitter, mcp_manager, memory_handler, permission, session, task_graph) for maintainability.

MCP (Model Context Protocol) integration connects to external tool servers via stdio, SSE, and Streamable HTTP transports, with config-driven server lifecycle management, trust-based permissions, improved server discovery, server diagnostic summaries, in-app resource and prompt browsing, and an in-app marketplace combining a built-in catalog with remote catalog sources for one-click install. A native skills system provides reusable prompt, tool, and workflow capabilities with config-driven discovery, plugin-namespaced skill roots, SkillHub install support, permission summaries, and GUI settings management. Per-project configuration is discovered under .kairox/ directories, and the GUI supports project workspace flows for managing multiple working contexts.

Built-in tools include filesystem access (fs.read, fs.write, fs.list), shell.exec, patch.apply, ripgrep-backed search.ripgrep, monitor tools (monitor.start, monitor.list, monitor.stop), Playwright-backed browser automation (browser.action, browser.batch), and desktop interaction (computer.use). Build info (version, git hash, build time) is embedded at compile time and accessible from both TUI and GUI.

Trajectory recording primitives now live in agent-core and agent-store: trajectories capture ordered action/observation steps, optional screenshot IDs, timing, outcomes, and JSON export for future replay/eval tooling.

The desktop app ships with Tauri 2 auto-update wired to GitHub Releases. Release packaging includes SHA256 checksums and structured artifact naming. CI runs E2E tests alongside parallel jobs with type-sync checks via tauri-specta, an aggregation ci-success job for branch protection compatibility, real desktop E2E via tauri-pilot, and a live GitHub Models smoke test.

GUI test coverage spans stores, composables, and components, with additional MCP E2E tests and dedicated DAG executor / AgentStrategy / GUI component test suites. The kairox-eval harness now supports scenario listing, tag filtering, fail-fast execution, forbidden event and budget expectations, JSONL results, summary JSON, and combined report JSON. The frontend toolchain uses the Oxc toolchain (oxlint + oxfmt) for fast linting and formatting. The GUI features a complete frontend engineering foundation with vue-router, vue-i18n, and Pinia setup stores.

Requirements

• Rust stable toolchain
• Node.js 22+
• Bun 1.3+

For Tauri desktop packaging:

• macOS: Xcode Command Line Tools
• Linux: WebKitGTK and Tauri native dependencies (see ci.yml for the full list)
• Windows: WebView2 toolchain

Demo

Run cargo run -p agent-tui for a live demo of the interactive TUI with streaming chat, tool trace, and sidebar controls.

Why Kairox?

Kairox aims to provide a local-first foundation for AI agent workflows with explicit boundaries between shared core logic, runtime orchestration, model integration, and user interfaces.

Getting started

If you want to try Kairox quickly, start with the local setup and quality gates below, then run either the TUI or the GUI shell.

Install dependencies

bun install

Run quality gates

just check

Or individually:

just fmt-check      # format check
just lint           # clippy + oxlint + stylelint
just test           # cargo test
just check-types    # Rust ↔ TypeScript type sync

Install just with cargo install just or brew install just.

Run TUI

just tui

Run GUI (Vite dev server)

just gui-dev

Run Tauri desktop app in development

just tauri-dev

This starts the Vite dev server and the native Tauri window together, providing hot-reload for both the frontend and the Rust backend.

Build GUI web assets

just gui-build

Build Tauri desktop app

just tauri-build

Tooling

Repository-level quality tooling includes:

• oxfmt for frontend/docs formatting
• oxlint for Vue/TS linting
• Stylelint for styles and Vue style blocks
• cargo fmt for Rust formatting
• cargo clippy for Rust linting
• Husky + lint-staged for pre-commit enforcement
• commitlint for Conventional Commits on commit-msg

Useful commands (with just):

just check        # full CI gate: format + lint + test
just fmt          # auto-format all code
just tui          # run the TUI app
just gui-dev      # run the GUI dev server
just bump-version X.Y.Z  # bump version in all config files
just check-types  # verify Rust ↔ TypeScript EventPayload sync
just gen-types    # regenerate Tauri command TypeScript bindings
just worktree <branch>  # create .worktrees/<sanitized-branch> and run bun install

Or the underlying Bun/cargo commands:

bun run format
bun run format:check
bun run lint

Releases and packaging

GitHub Actions are configured to:

• run CI checks on pushes and pull requests
• build TUI binaries
• build GUI web assets
• build Tauri desktop bundles on macOS, Linux, and Windows

See the latest release for downloadable assets.

Contributing

1. Create a feature branch
2. Keep commits in Conventional Commit format
3. Run local checks before pushing
4. Open a pull request using the provided template

For isolated development, use just worktree feat/my-feature. Worktrees are created under the ignored .worktrees/ directory using a path-safe branch name, for example .worktrees/feat-my-feature.

Automation

This repository also includes:

• Dependabot for Bun, Cargo, and GitHub Actions dependency updates
• GitHub Release Notes configuration via .github/release.yml
• Automatic GitHub Release publishing on v* tags
• GitHub Discussions for questions and design discussion

Discussions

Use GitHub Discussions for questions, design ideas, and broader product conversations. Use Issues for actionable bugs and feature work.

License

Apache License 2.0. See LICENSE.