Skip to content

tmoreton/kai

BranchesTags

Repository files navigation

Kai

AI coding assistant with persistent memory, background agents, and tool use. Powered by OpenRouter.

📖 Full documentation: https://kai-docs-three.vercel.app/ — guides for Web UI, CLI, and Skills

Quick Start

# Install dependencies
npm install

# Set up your API key
cp .env.example .env
# Edit .env and add your OpenRouter API key

# Run in development
npm run dev

# Or build and run
npm run build
npm start

Features

  • Interactive REPL — streaming responses with tool calling and markdown rendering
  • Persistent memory — soul (identity), archival (long-term knowledge), recall (conversation history)
  • Background agents — schedule autonomous workflows with cron via YAML definitions
  • Web UI — browser-based chat interface with SSE streaming
  • 20+ tools — bash, file ops, web search/fetch, git, MCP servers, screenshot, vision
  • Sub-agents — spawn explorer, planner, and worker agents for complex tasks
  • Skills — External skill system for integrations:
    • openrouter — Image generation (Gemini 3 Pro)
    • youtube — YouTube analytics
    • browser — Web automation
    • email — Send notifications
    • data-storage — JSON/Markdown files
    • docker, git, notion, slack, twitter, etc.
    • Install: kai skill install <name> or npx kai-skills install <skill>
    • Registry: https://www.npmjs.com/package/kai-skills
  • Project-aware — auto-detects project root and scopes memory per-project
  • Self-improving agents — workflows can include a review loop for quality iteration

Architecture

src/
├── index.ts              # CLI entry point (Commander)
├── client.ts             # LLM client + tool execution loop
├── repl.ts               # Interactive REPL with slash commands
├── system-prompt.ts      # System prompt builder
├── config.ts             # Config loading (settings.json, env)
├── constants.ts          # All shared constants (timeouts, limits, retries)
├── utils.ts              # Shared utilities (retry, path resolution)
├── context.ts            # Token tracking & auto-compaction
├── permissions.ts        # Tool permission rules & confirmation
├── commands.ts           # Custom slash commands
├── sessions.ts           # Session persistence
├── project.ts            # Project detection & scoping
├── soul.ts               # Core memory (persona, human, goals, scratchpad)
├── archival.ts           # Long-term knowledge store (JSONL)
├── recall.ts             # Conversation history archive
├── project-profile.ts    # Per-project metadata
├── subagent.ts           # Specialized sub-agents (explorer/planner/worker)
├── git.ts                # Git utilities
├── diff.ts               # Diff rendering
├── render.ts             # Markdown rendering for terminal
├── hooks.ts              # Before/after hooks for tools
├── tools/
│   ├── definitions.ts    # Tool schemas (OpenAI format)
│   ├── executor.ts       # Tool dispatcher + permission checks
│   ├── bash.ts           # Shell command execution
│   ├── files.ts          # File read/write/edit
│   ├── search.ts         # Glob & grep
│   ├── web.ts            # Web fetch & Tavily search
│   ├── mcp.ts            # Model Context Protocol client
│   ├── screenshot.ts     # Screen capture (macOS)
│   ├── vision.ts         # Image analysis
│   └── index.ts          # Tool exports
├── skills/
│   ├── loader.ts         # External skill loader (~/.kai/skills/)
│   ├── executor.ts       # Skill tool execution
│   ├── types.ts          # Skill manifest types
│   └── installer.ts      # Skill installation helper
├── agents-core/          # Background agent platform
│   ├── db.ts             # SQLite agent database
│   ├── daemon.ts         # Cron scheduler & event loop
│   ├── manager.ts        # Agent CLI interface
│   ├── workflow.ts       # YAML workflow engine
│   └── bootstrap.ts      # Agent initialization
├── agents/               # Agent subsystems
│   ├── event-bus.ts      # Event-driven triggers
│   ├── scheduler.ts      # Cron & heartbeat
│   ├── runner*.ts        # Agent execution
│   └── watchers/         # File/email watchers
├── skills/               # External skill system
│   ├── loader.ts         # Skill discovery & loading (~/.kai/skills/)
│   ├── executor.ts       # Skill tool execution
│   ├── types.ts          # Skill manifest types
│   └── installer.ts      # Skill installation helper
├── providers/
│   └── index.ts          # LLM provider resolution (Fireworks/OpenRouter)
└── web/
    ├── server.ts         # Hono HTTP server + SSE streaming
    └── public/
        └── index.html    # Web UI (SPA)

Configuration

Kai loads config from (highest priority first):

  1. .kai/settings.json (project-level)
  2. kai.config.json (project-level)
  3. ~/.kai/settings.json (user-level)

Settings

{
  "model": "moonshotai/kimi-k2.5",
  "mcp": {
    "servers": {
      "example": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
        "env": {}
      }
    }
  },
  "permissions": {
    "mode": "default",
    "allow": [],
    "deny": []
  },
  "hooks": {
    "before": {},
    "after": {}
  }
}

Environment Variables

Variable Required Description
OPENROUTER_API_KEY Yes OpenRouter API key
MODEL_ID No Override default model (default: moonshotai/kimi-k2.5)
TAVILY_API_KEY No Enable web search via Tavily
YOUTUBE_API_KEY No Enable YouTube agent features

CLI Commands

# Interactive REPL
kai

# One-shot query
kai "explain this codebase"

# Continue / resume sessions
kai --continue             # Resume most recent session
kai --resume <id>          # Resume specific session
kai --name "my session"    # Name the session
kai --yes                  # Auto-approve all tool calls

# Pipe input
echo "explain this" | kai
cat file.ts | kai "review this code"

# Web server (API + UI + agent daemon)
kai server                 # Start on port 3141
kai server --port 3000     # Custom port
kai server --no-ui         # API + agents only
kai server --no-agents     # API + UI only

# Agent management
kai agent list             # List all agents
kai agent create <name> <workflow.yaml> [--schedule "0 */6 * * *"]
kai agent run <id>         # Run an agent now
kai agent output <id>      # View latest output
kai agent info <id>        # Agent details + run history
kai agent delete <id>      # Delete an agent
kai agent daemon           # Start the cron scheduler
kai agent stop             # Stop the scheduler

# MCP servers
kai mcp list               # List configured servers + tools

REPL Commands

Command Description
/help Show all available commands
/clear Clear conversation (keep system prompt)
/compact Compress context to save tokens
/sessions List recent sessions
/soul View core memory + recall stats
/diff Show all changes made this session
/git Git status + changed files
/git diff Colorized diff (staged + unstaged)
/git log [n] Recent commits (default 15)
/git undo [n] [hard] Undo last N commits + clear conversation
/git stash [msg] Stash uncommitted changes
/git commit [msg] [--push] AI-generated commit + optional push
/git pr [title] Create PR (branch + commit + push + open)
/git branch [name] List or create/switch branches
/agent List background agents
/agent run <id> Run an agent now
/agent output <id> View agent output
/agent info <id> Agent details + run history
/skill List loaded skills
/skill reload Reload all skills (hot reload)
/mcp List connected MCP servers + tools
/mcp add <name> <cmd> Add an MCP server
/mcp remove <name> Remove an MCP server
/doctor Run system diagnostics
/notify Show agent notifications
/notify --all Show all notifications
/export [path] Export session to markdown file
/plan Toggle plan mode
/review AI code review of current git changes
/security-review Security-focused audit of git changes
/exit Exit Kai

Custom commands can be added as markdown files in .kai/commands/.

Tools

Kai's LLM has access to these tools:

Tool Description
bash Run shell commands (working directory persists)
bash_background Start long-running processes (returns PID)
read_file Read files with line numbers, offset/limit
write_file Create or overwrite files
edit_file Targeted text replacements
glob Find files by pattern
grep Search file contents with regex
web_fetch Fetch URL content (HTML → readable text)
web_search Web search via Tavily
generate_image Image generation via OpenRouter
take_screenshot Capture screen for vision analysis
analyze_image Analyze images with vision model
core_memory_read Read identity/context memory
core_memory_update Update persona, human, goals, scratchpad
search_recall Search past conversation history
archival_memory_insert Store long-term knowledge
archival_memory_search Search long-term knowledge
spawn_agent Spawn subagents (explorer/planner/worker)
spawn_swarm Spawn multiple agents in parallel
skill__* Dynamic tools from external skills (~/.kai/skills/)

Models

All models are accessed via OpenRouter:

Role Model ID
Primary Kimi K2.5 moonshotai/kimi-k2.5
Fallback Qwen3 235B qwen/qwen3-235b-a22b
Image Gen Gemini 2.5 Flash google/gemini-2.5-flash-image

Override with MODEL_ID in .env or "model" in settings.json.

Memory System

Kai has three memory layers:

Layer Purpose Storage
Soul Persistent identity (persona, human) + per-project context (goals, scratchpad) ~/.kai/soul/ + ~/.kai/projects/{id}/
Archival Long-term knowledge store, searchable by keyword and tags ~/.kai/projects/{id}/archival/ (JSONL)
Recall Searchable archive of past conversations across sessions ~/.kai/projects/{id}/recall/ (JSONL)

Memory is scoped per-project (auto-detected via .git, package.json, etc.).

Background Agents

Agents run autonomous YAML workflows on a cron schedule. Example:

name: nightly-commit
description: Auto-commit config changes
schedule: "0 2 * * *"
steps:
  - name: check_changes
    type: shell
    command: "cd ~/.kai && git status --porcelain"
  - name: generate_message
    type: llm
    prompt: "Generate a commit message for: ${vars.check_changes}"
  - name: commit
    type: shell
    command: "cd ~/.kai && git add -A && git commit -m '${vars.generate_message}'"

Workflow Step Types

Type Description
llm Send a prompt to the LLM, store the response
integration Call a built-in integration (youtube, data, web, image, mcp)
shell Run a shell command
notify Send a desktop notification
review Self-improvement review loop

Built-in Integrations

Integration Actions
youtube search_videos, get_video_stats, get_channel, get_recent_uploads, get_trending
data read, write, append, archive, read_text, list_files
web Web search via Tavily
image Image generation via OpenRouter
mcp Call tools on configured MCP servers

Web API

When running kai server, these endpoints are available:

Endpoint Method Description
/api/status GET Server status, model, usage
/api/chat POST Chat with SSE streaming
/api/chat/stop POST Cancel a streaming response
/api/sessions GET List sessions
/api/sessions/:id GET Get session messages
/api/sessions POST Create new session
/api/sessions/:id DELETE Delete session
/api/agents GET List agents
/api/agents/:id GET Agent details + runs
/api/agents/:id PATCH Edit agent (toggle, rename, schedule)
/api/agents/:id DELETE Delete agent
/api/agents/:id/run POST Run agent
/api/agents/:id/output GET Latest run output
/api/agents/:id/recap GET LLM-generated run summary
/api/agents/:id/logs GET Agent logs
/api/agents/:id/runs/:runId GET Steps for a specific run
/api/models GET Available models (cached)
/api/image GET Serve local image files

License

ISC

About

AI coding assistant with persistent memory

www.kaiskills.com

Resources

Readme

License

Apache-2.0 license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

v1.0.0 Latest
Apr 10, 2026

Packages

 
 
 

Contributors

Languages