Kai

A personal AI assistant on your own machine.

~1,000 lines of Python · Apache 2.0

Kai is a Telegram gateway to Claude Code. Messages you send in Telegram are forwarded to a persistent Claude Code subprocess running on your machine. Claude has full tool access — shell commands, file editing, web search, code review — and responses stream back in real time.

Other projects in this space route your messages through third-party servers, manage their own tool-use layers, and distribute plugins through marketplaces where 7% of submissions leak credentials. Kai takes the opposite approach: delegate to Claude Code, run locally, trust nothing you didn't put there yourself. The result is a small codebase with a large capability surface and no third-party dependencies in the agent runtime.

On a Max plan, all usage is covered by the subscription — no per-token API costs, no surprise bills. The session budget cap prevents runaway work. The only external connections are to the Telegram Bot API and Anthropic's API, both authenticated and encrypted. Everything else stays on your hardware.

How it works

Telegram →

Kai (your machine) →

Claude Code (shell, files, web, git)

Kai is the thin layer in the middle. It handles Telegram I/O, workspace management, scheduling, and webhooks. Claude Code handles everything else.

Design choices

Telegram only. Best bot API available: message editing for streaming, inline keyboards for interactive UI, file handling, slash commands, unlimited free messaging. No other platform offers all of these. Supporting 13 platforms means maintaining 13 platform-specific integrations — complexity that serves multi-user products but adds overhead for a single-user tool.

Claude Code only. Why rebuild what already exists? Claude Code provides shell, files, web search, and code editing in a single subprocess. Kai delegates to it and focuses on what it adds. The result is ~1,000 lines of Python that punch far above their weight.

Local only. Enables flat-rate Max plan auth, macOS-native integrations (Calendar, Music, Reminders via AppleScript), and an unambiguous security boundary. A VPS would trade all three for always-on hosting — which launchd or systemd already provide on any local machine.

Features

Streaming responses

Responses stream into Telegram in real time. The message updates every two seconds as Claude generates text — you see thinking happen, not just results.

> What does the deploy script do?

█ Reading deploy.sh... The script runs three steps:
  1. Builds the Docker image...

Workspace switching

Point Kai at any repo on your machine. Your identity and personal memory carry over; project-specific context loads automatically. Manage multiple codebases from your phone.

/workspace kai-web
Switched to /Users/you/Projects/kai-web
Memory loaded: 3 layers (auto + home + workspace)

Scheduled jobs

Set reminders or recurring Claude tasks with natural language. Conditional jobs monitor for events and notify you when a condition is met — then deactivate themselves.

"Remind me to check the deploy at 3pm"
"Let me know when the PR is merged" (checks every hour, auto-removes when done)

GitHub notifications

Pushes, pull requests, issues, and reviews arrive in Telegram as formatted messages. Webhook signatures are HMAC-validated. You stay informed without checking GitHub.

Persistent memory

Three layers of memory survive session resets: auto-memory (how the project works), home memory (who you are), and workspace memory (what's happening here). Kai remembers across restarts, model switches, and workspace changes.

Security

Kai was built as a replacement for an OpenClaw-based setup after encountering security and trust concerns with that ecosystem. The differences are architectural:

— No plugin marketplace. Claude Code skills are local files on your filesystem, not packages from a registry.
— No API key management. Auth is handled by Claude Code's own claude login.
— No public-facing control plane. The only internet-exposed endpoints are HMAC-validated webhooks and a health check.
— One Claude instance, one user, one direction. No multi-agent routing or shared message buses.

Get started

install

git clone git@github.com:dcellison/kai.git
cd kai
python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
cp .env.example .env

configure

# Edit .env with your values:
#   TELEGRAM_BOT_TOKEN  — from @BotFather
#   ALLOWED_USER_IDS    — from @userinfobot

run

python -m kai

Requires Python 3.13+ and Claude Code CLI installed and authenticated.