Configuration

Environment variables

Create a .env file in the project root (see .env.example for a template).

Required

Variable	Description
TELEGRAM_BOT_TOKEN	Bot token from BotFather.
WHITELIST	Comma-separated Telegram user IDs allowed to use the bot. Get your ID with @userinfobot.

Optional

Variable	Default	Description
CLAUDE_BIN	claude	Path to the Claude Code binary.
CLAUDE_MODEL	sonnet	Default model for Claude sessions (haiku, sonnet, opus).
SESSIONS_DIR	./sessions	Directory where per-user session state is stored.
REPOS_DIR	./repos	Shared directory for all cloned repositories.
IDLE_TIMEOUT_MS	600000	Idle timeout in milliseconds (default: 10 minutes).

Example .env file

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
WHITELIST=111222333,444555666
CLAUDE_MODEL=sonnet
IDLE_TIMEOUT_MS=600000

Directory structure

Repositories are stored in a shared repos/ directory. Each user’s active repo selection is tracked under sessions/.

repos/
  <repo-name>/                  ← shared git clone (read-only by convention)

sessions/<chat_id>/
  .active_repo                  ← which shared repo this user is using

Multiple users can access the same repository without duplicating storage. No manual cleanup needed — just delete the directories to remove data.

Custom commands

Define additional slash commands in commands.json (create it next to .env):

[
  {
    "command": "review",
    "description": "Run a code review",
    "prompt": "Run a thorough code review of the current diff against master. Focus on: bugs, security issues, performance problems, and code quality. Format output with clear sections."
  },
  {
    "command": "explain",
    "description": "Explain selected code",
    "prompt": "Explain the following code in detail, including what it does, why it works, and any potential issues:\n\n{{args}}"
  }
]

The {{args}} placeholder is replaced with whatever text the user passes after the command name. See Custom Commands for full details.