Skip to content

Getting Started

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

Getting Started

You've installed Kai, configured .env, and started it up. Here's what to do next.

First run

When Kai starts successfully, you'll see:

Kai starting (model=sonnet, users={your-user-id})
Telegram transport: polling (TELEGRAM_WEBHOOK_URL not set)
Kai is running. Press Ctrl+C to stop.

By default Kai uses long polling - no tunnel or public URL needed. If you've set TELEGRAM_WEBHOOK_URL in .env, you'll see Telegram transport: webhook instead. See Exposing Kai to the Internet for webhook setup.

If it exits immediately, check the Troubleshooting page.

Your first conversation

  1. Open Telegram and find your bot (search for the name you gave it in BotFather)
  2. Tap Start or send /start — Kai replies "Kai is ready. Send me a message."
  3. Type a message — anything you'd ask Claude. Kai forwards it to Claude Code with full tool access.

You'll see a typing indicator while Claude works, then the response streams in with live message edits every 2 seconds.

Try the basics

Ask a question:

What's the weather like in San Francisco?

Claude has web search access and will look it up.

Send a file: Drop a Python script, JSON file, or image into the chat. Kai passes it to Claude with full context.

Send a voice note: If you enabled VOICE_ENABLED=true, send a Telegram voice message. Kai transcribes it locally, echoes the transcription, then responds.

Explore commands

Type /help to see all available commands. Some highlights:

  • /models — tap to switch between Opus (most capable), Sonnet (balanced), and Haiku (fastest)
  • /stats — see your current session info and cost
  • /new — clear the conversation and start fresh
  • /stop — interrupt Claude mid-response if it's going off track

Set up workspaces

If you set WORKSPACE_BASE in .env (e.g., /home/you/projects), you can point Kai at any project:

/workspace myproject     → switches to ~/projects/myproject
/workspace home          → back to the default workspace
/workspace new experiment → creates ~/projects/experiment with git init
/workspaces              → interactive picker of recent workspaces

For existing projects outside WORKSPACE_BASE, add them to ALLOWED_WORKSPACES:

ALLOWED_WORKSPACES=/home/you/other-project,/home/you/legacy-app

These appear as pinned entries in /workspaces and are reachable by name (e.g., /workspace other-project).

When Kai switches workspaces, it restarts the Claude session with the new project's context while preserving your identity and personal memory from the home workspace.

For per-workspace model, budget, timeout, environment variables, and system prompts, see Workspaces - Per-workspace configuration.

Schedule a reminder

Ask naturally:

Remind me to check the CI pipeline at 3pm

Kai creates the job via its scheduling API. Check active jobs with /jobs and cancel with /canceljob <id>.

What's happening under the hood

When you send a message, Kai:

  1. Checks your Telegram user ID against the allow list (users.yaml or ALLOWED_USER_IDS)
  2. On the first message of a session, injects your identity, memory, recent history, and API info
  3. Pipes your message to a persistent Claude Code subprocess
  4. Streams the response back with live Telegram edits
  5. Saves the session for cost tracking

Claude Code runs with full tool access — shell commands, file operations, web search, code editing — all on your local machine. See System Architecture for the full picture.

Next steps

Clone this wiki locally