Skip to content

Home

Jump to bottom
Daniel Ellison edited this page Jun 22, 2026 · 33 revisions

Kai Wiki

Kai wraps persistent AI agent processes running on your hardware and connects them to Telegram as a control surface. The default backend is Claude Code, but Kai also supports Goose with providers like OpenAI, Google, OpenRouter, and local models via Ollama. Shell, filesystem, git, web search, scheduling - the agent has real access to your system and can take real action on it. It reviews PRs when code is pushed, triages issues when they're opened, monitors conditions on a schedule, and operates across any project on your machine. Multiple users can share a single instance with full isolation, each on their own backend and provider if needed.

Everything runs locally. Conversations never transit a relay server. API keys are proxied through an internal service layer so they never appear in conversation context.

Getting started

New here? Start with the README for installation, then come back for the rest.

  • Getting Started — Your first conversation, key commands, and how Kai works under the hood.
  • Troubleshooting — Common issues and fixes for startup, Claude errors, voice, webhooks, and services.

Setup guides

  • Multiple Backends — Why Kai supports multiple agent backends, how the abstraction works, configuration for each provider, and choosing the right one.
  • Installing Agent Binaries — How and where to install backend binaries so every OS user can reach them, with per-backend guidance and what to avoid.
  • Exposing Kai to the Internet — Cloudflare Tunnel setup, security model, and alternatives (ngrok, reverse proxy). Required for Telegram webhook mode and GitHub webhooks.
  • Multi-User Setup — Serve multiple Telegram users from one instance with per-user subprocesses, isolated data, roles, and optional OS-level separation.
  • Protected Installation — Production deployment to /opt/kai with separated source, data, and secrets. User separation and service management.
  • Configuration Wizard — Every prompt in make config explained: what it controls, valid values, when it appears, and how to choose.
  • TOTP Authentication — Optional two-factor authentication that gates Claude startup with an authenticator app code.
  • Voice Setup — Voice input (whisper.cpp STT) and voice output (Piper TTS): dependencies, models, available voices, and troubleshooting.
  • Browser Automation — Playwright CLI setup for headless browsing, screenshots, scraping, and web interaction.

Reference

  • Slash Commands — Complete reference for every Telegram command, subcommand, argument, and behavior.

Features

  • PR Review Agent — Automatic code review on pull requests: diff analysis, spec compliance checking, and convention enforcement via a one-shot Claude subprocess.
  • Issue Triage Agent — Automatic issue labeling, duplicate detection, project assignment, and priority assessment via a one-shot Claude subprocess.
  • Scheduling and Conditional Jobs — Reminders, recurring Claude jobs, conditional monitoring with auto-remove, and the HTTP scheduling API.
  • Workspaces — Switch between projects, per-workspace configuration (model, env, system prompts), memory injection, and the interactive picker.
  • Memory — Persistent semantic memory built on Mem0 and Qdrant: facts, episodes, retrieval, the /memory dashboard, and how the three-layer memory model fits together.
  • External Services — Declarative service proxy for calling external APIs (Perplexity, weather, notifications) without exposing API keys.
  • GitHub Notification Routing — Route GitHub event notifications to a separate Telegram group to keep your DM clean.
  • Webhook Examples — Generic webhook integrations: CI/CD, monitoring, home automation, Docker, deployments, and more.

Design

  • System Architecture — How Kai's components fit together: message lifecycle, workspace switching, three-layer memory system, and concurrency model.
  • Inner Claude Context Sequence - The full ordering of what lands in inner-Claude's context window: phase 1 binary startup, phase 2 Kai's prepended block, what fires per-turn vs once, and foreign-workspace specifics.
  • Testing — Test suite structure, common patterns, and how to write new tests.

Clone this wiki locally