Skip to content

Home

Jump to bottom
Daniel Ellison edited this page Mar 22, 2026 · 21 revisions

Kai Wiki

Kai wraps persistent Claude Code processes running on your hardware and connects them to Telegram as a control surface. 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.

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

  • 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.
  • 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.

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, budget, env, system prompts), memory injection, and the interactive picker.
  • External Services — Declarative service proxy for calling external APIs (Perplexity, weather, notifications) without exposing API keys.
  • 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.
  • Testing — Test suite structure, common patterns, and how to write new tests.

Clone this wiki locally