🌐  koi.ink  ·  📖  Docs  ·  📦  npm

⚡ Quick Start

# macOS / Linux
curl -fsSL https://koi.sh/install.sh | bash

# Windows
irm https://koi.sh/install.ps1 | iex

# From source
git clone https://github.com/meowlynxsea/koi.git && cd koi && bun install

Then run koi in any project directory.

ACP Agent Mode

Koi supports the Agent Client Protocol (ACP), allowing any ACP-compatible editor (VS Code, Zed, Cursor, etc.) to connect to Koi as a backend agent:

# Start Koi in ACP mode
koi --acp

In ACP mode, Koi communicates via JSON-RPC over stdio and exposes its full agent capabilities — tools, MCP integration, skills, and context engine — to the connected client.

🎨 What is KOI?

KOI (Keep on Improving) is a TUI coding agent that builds a living semantic map of your entire codebase — every function, every type, every relationship — stored locally on your machine.

Built with OpenTUI React on the Bun runtime. Every frame at 60fps. Every keystroke, instant.

┌──────────────────────────────────────────────────────────────────────────┐
│  koi — zsh                        [Build]  [Ask]  [Plan]                │
├──────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  $ koi                                                                   │
│  KOI v0.2.20 — Keep on Improving                                         │
│                                                                          │
│  Build > Analyze and optimize this React component                      │
│  [KOI] Scanning codebase...                                              │
│  [KOI] Found 3 optimization points in 2 files                            │
│  [KOI] Applied changes ✓                                                 │
│                                                                          │
│  Ask > Explain the auth flow without changing anything                  │
│  [KOI] Reading auth.ts, middleware.ts, user-store.ts...                 │
│  [KOI] The auth flow uses JWT tokens with refresh rotation...            │
│                                                                          │
│  Build > █                                                               │
└──────────────────────────────────────────────────────────────────────────┘

✨ Core Features

🎭 Three Modes

Press Tab to switch. Each mode has its own tool allowlist and safety profile.

| Mode | Tools | Write | |:----:|:-----:|:-----:| | Build | All 20+ | ✅ | | Ask | Read-only | ❌ | | Plan | Read + Tasks | ❌ |

🧠 Cat's Context Engine

Your codebase, deeply understood.

• Local embeddings (BERT, 384-dim)
• Knowledge graph with semantic links
• 12-slot working memory
• File watcher auto-sync
• Dream consolidation every 30min

🧩 Skills Ecosystem

Teach KOI your conventions.

• SKILL.md with YAML frontmatter
• Auto-discover from ~/.config/koi/skills
• Conditional activation by path
• Slash command invocation
• Claude-compatible format

🔌 MCP Native

Connect any MCP server instantly.

| Transport | Protocol | |-----------|----------| | stdio | Local executable | | SSE | Server-Sent Events | | HTTP | REST API | | WebSocket | Real-time |

🖥️ Fluid TUI

A terminal UI that feels alive.

• 60fps React rendering
• Bracketed paste & image preview
• Ink-wave idle animations
• Real-time cost tracking
• Screenshot analysis

🔒 Privacy First

Your code never leaves your machine.

• 100% local embeddings
• GPL-3.0 open source
• Customizable modes & prompts
• Own MCP servers & skills
• Own external editor

🚀 Usage

Keyboard Shortcuts

| Key | Action | Key | Action | |:---:|:-------|:---:|:-------| | Shift+Tab | Cycle modes | Ctrl+S | Manage sessions | | Ctrl+G | External editor | Ctrl+F | Fork session | | Ctrl+V | Paste Image | Ctrl+C | Cancel operation |

📂 Project Structure

koi/
├── src/
│   ├── agent/          # Core agent & orchestration
│   ├── cce/            # Cat's Context Engine
│   ├── cli/            # CLI parsing
│   ├── commands/       # Slash commands
│   ├── config/         # Settings
│   ├── services/       # LLM providers, costs
│   ├── skills/         # Built-in skills
│   ├── tools/          # Agent tools
│   └── tui/            # OpenTUI components
├── native/             # Native modules
├── website/            # Docs site (koi.ink)
└── examples/skills/    # Skill templates

🛠️ Development

git clone https://github.com/meowlynxsea/koi.git
cd koi
bun install
bun run dev        # Development mode
bun run build      # Production build
bun run check      # Type check
bun run lint       # Lint

📚 Documentation

Full documentation at koi.ink

• Quick Start · Installation · First Run · FAQ

• Interface · Agent Modes · Sessions · Tools · Keyboard

• CCE Overview · Working Memory · Knowledge Graph · Boot Links · Semantic Search

• Using Skills · Creating Skills · MCP Servers · LLM Providers · External Editor

• Configuration · Subagents · Permissions · Context Compaction

🌐 koi.ink · 📖 Docs · 💻 GitHub · ⚖️ GPL-3.0

Keep on Improving