Skip to content

Home

Jump to bottom
Daniel Ellison edited this page Sep 11, 2026 · 2 revisions

Kai Wiki

Kai wraps persistent AI agent processes running on your hardware, with two ways in: the Workshop, a browser client where people and agents work in shared channels, and Telegram as an optional chat surface. Agents run on whichever backend the admin selects at install: Claude Code, OpenAI's Codex CLI, Goose, OpenCode, or Pi. Between them the backends cover providers like OpenAI, Google, DeepSeek, OpenRouter, GitHub Copilot, 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 on either surface, key commands, and how Kai works under the hood.
  • Troubleshooting - Common issues and fixes for startup, Claude errors, voice, webhooks, and services.

Workshop

The browser client, and the native way to use Kai.

  • Workshop Collaboration Basics - Enrolling a browser, channels and direct messages, threads, mentions, reactions, artifacts, and agent runs.
  • Workshop Agents - Creating agents, definition revisions, collaboration tools, delegation, and how agents behave in channels.
  • Standing Participation - Agents that keep watching an opted-in channel and choose for themselves when to contribute, under strict budgets.
  • Workshop Memory Explorer - Browsing, searching, and curating what Kai remembers about you.
  • Workshop Settings - Profile and avatar, personal preferences, GitHub automation, notification delivery, themes, and voice.
  • Workshop Operator Guide - Client modes, the access lifecycle, network exposure, the workshop CLI, and diagnostics.

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 people from one instance: canonical principals, Workshop provisioning, Telegram linking, isolated data, 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 agent startup on the Telegram surface with an authenticator app code. Workshop browser auth uses enrollment tokens instead.
  • 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-surface 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: the canonical event-store core, the run execution chain, the delivery outbox, and the client surfaces around them.
  • Agent Context Sequence - The full ordering of what lands in an agent's context window on any backend: binary startup, 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