minbot: Minimal Telegram Bot for GitHub Development

A lightweight Telegram bot that monitors GitHub issues, estimates difficulty/urgency, suggests what to work on, and can autonomously work on issues using Claude Code.

📏 Core bot in 1152 lines of Python (run bash core_lines.sh to verify)

Quick Start

1. Get your tokens

Token	Where to get it
GitHub Token	github.com/settings/tokens (scopes: repo)
Telegram Bot Token	Talk to @BotFather on Telegram

2. Clone and configure

git clone git@github.com:ChicagoHAI/minbot.git
cd minbot

Create ~/.minbot/config.json:

{
  "telegram_token": "your-telegram-bot-token",
  "github_token": "ghp_...",
  "github_repos": ["owner/repo", "owner/repo2"]
}

Optionally add "anthropic_api_key": "sk-ant-..." to use the Anthropic SDK instead of the claude CLI for issue analysis.

3. Run

USER_UID=$(id -u) USER_GID=$(id -g) docker compose up --build -d

This builds the image with your user ID (so mounted files are accessible), installs Python deps and the Claude CLI, and starts the bot.

Open Telegram and send /start to your bot. The first user to /start claims the bot — their chat ID is saved and all commands from other users are ignored.

Running without Docker

One-liner:

curl -fsSL https://raw.githubusercontent.com/ChicagoHAI/minbot/main/install.sh | bash

Or clone and install manually:

git clone git@github.com:ChicagoHAI/minbot.git
cd minbot
bash install.sh

Then configure and run:

uv run python -m minbot setup      # interactive config
uv run minbot                      # start the bot

Commands

Command	Description
/start	Show available commands
/issues [repo]	List open issues with difficulty/urgency estimates
/suggest [repo]	Get a recommendation on what to work on next
/work <number>	Work on an issue (single repo)
/work <repo> <number>	Work on an issue in a specific repo
/pr <number> [comments]	Address PR review comments
/pr <repo> <number> [comments]	Address PR review comments in a specific repo
/review [repo]	Run a code review on the codebase
/repos	List configured repos
/status	Check progress of current work

How /work works

When you send /work 42, minbot will:

1. Clone/pull the repo into workspace_dir/<owner>/<repo>
2. Create a branch issue-42
3. Spawn Claude Code CLI with the issue context
4. Claude Code makes changes, commits, and pushes
5. minbot creates a PR and sends you the link

How /pr works

When you send /pr 7 please fix the formatting too, minbot will:

1. Fetch the PR details and all review comments from GitHub
2. Clone/pull the repo and checkout the PR branch
3. Run Claude Code with the PR context, review comments, and your additional instructions
4. Claude addresses the comments, commits, and pushes to the same branch
5. Report the result back via Telegram

Periodic Code Review

When review_interval_hours is configured, minbot periodically reviews each repo:

• 70% chance: picks a random open PR and reviews it (overall assessment, key concerns, unaddressed comments)
• 30% chance: reviews the whole codebase for bugs, quality improvements, and performance issues

You can also trigger a review manually with /review [repo].

Issue Analysis

minbot uses Claude to analyze issues and suggest what to work on. It supports two modes:

• Claude CLI (default): Calls the claude CLI as a subprocess. Requires claude to be installed and authenticated.
• Anthropic SDK: Set anthropic_api_key in config.

Configuration

All config lives in ~/.minbot/. The full set of options in config.json:

Key	Default	Description
telegram_token	(required)	Telegram bot token
github_token	(required)	GitHub token with repo scope
github_repos	(required)	List of repos in owner/repo format
anthropic_api_key	null	If set, uses Anthropic SDK instead of Claude CLI
check_interval_hours	6	How often to check for new issues
suggest_interval_hours	24	How often to send work suggestions
review_interval_hours	null	How often to run periodic code reviews (disabled by default)
workspace_dir	"/workspace"	Where repos are cloned for /work

When running with Docker, workspace_dir must be a path inside the container. The default /workspace is backed by a Docker volume and persists across restarts. When running without Docker, set it to a local path (e.g. "/home/you/minbot_workspace").

Environment variables for /work

When Claude works on an issue, it may need API keys to run tests or experiments. Create ~/.minbot/.env with any variables your projects need:

OPENROUTER_API_KEY=sk-or-...
DATABASE_URL=postgres://...

These are automatically loaded into the Docker container and available to the Claude worker process.

Running Tests

uv run pytest tests/ -v

Project Structure

minbot/
  config.py      # Config loading from ~/.minbot/config.json
  github.py      # GitHub operations via PyGithub + git
  agent.py       # LLM reasoning via SDK or CLI (issue triage, suggestions)
  worker.py      # Claude Code subprocess for coding
  scheduler.py   # Periodic issue checking and proactive suggestions
  bot.py         # Telegram bot handlers (entry point)