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 user workspace data is stored.
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

Per-user workspaces

Each whitelisted user gets a private workspace at:

sessions/<chat_id>/
  default/
    <repo-name>/
      .active_workspace   ← marks active workspace
      .active_repo        ← marks active repo
      .active_branch      ← marks active branch
      ...                 ← cloned repo files
  <workspace-name>/
    <repo-name>/
      ...

Workspaces and repos are created on demand. 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.