claude-bot

A self-evolving, unattended AI programming bot powered by Claude Code.

claude-bot monitors GitHub issues, implements them autonomously via Claude Code, runs tests, opens PRs, reviews its own code, and merges — with no human in the loop. When idle, it patrols your repositories for bugs, outdated dependencies, and improvement opportunities, and files issues for itself to fix.

The bot is a seed: once deployed, each instance drifts toward its own codebase as it implements, patrols, and iterates. Two deployments of the same initial version will evolve differently over time.

Note: This is an early release. The core loop (schedule → implement → test → PR → merge) is stable, but several subsystems (Feishu integration, self-update deploy gate, cross-repo patrol) still have rough edges. See the open issues for known bugs.

What it does

• Autonomous implementation — picks up issues labeled claude, implements them with Claude Code, runs tests, opens a PR, performs AI code review, and merges
• Patrol — every 2 hours when idle: scans repos for bugs, anti-patterns, outdated deps, research opportunities, and cross-repo coherence gaps; files issues for itself to fix
• Self-introspection — clusters recurring errors from its own logs, files self-fix issues, and re-queues blocked jobs once a fix merges
• Self-update — pulls its own source on every merge to main, deploys atomically, rolls back on failure
• Watchdog — auto-restarts failing services, detects queue deadlocks, files alerts to GitHub
• Rate-limit recovery — backs off gracefully when the AI provider is overloaded, resumes automatically

Architecture

scheduler.py        Poll GitHub, enqueue jobs, AI priority + dependency analysis
worker.py           Claim jobs, run Claude Code, test, PR, review, merge
patrol.py           Idle-time code review / research / iteration patrol + self-introspection
watchdog.py         Extended watchdog: auto-file self-fix issues, re-queue on fix merge
self_edit.py        Cross-process lock preventing restarts while bot edits itself
bot_lease.py        GitHub-comment lease gate — prevents double-claiming across instances
model_registry.py   Provider / model configuration
provider.py         Rate-limit state machine
bin/
  self-update.sh    Closed-loop deploy: fetch → gate → rsync → restart → verify → rollback
  watchdog.sh       Service monitor, daily token report, backup, queue deadlock detection
  bash-guard.sh     PreToolUse hook — blocks git push, publish, ssh, secrets reads
  preflight.sh      Startup config validator
  smoke.py          Post-deploy smoke canary
.claude/
  agents/           implementer, reviewer, deep-reviewer agent definitions
  settings.json     Permission deny list + PreToolUse hooks
systemd/            Service and timer unit files
migrations/         Incremental SQLite schema migrations (idempotent)
repos.yml           Monitored repositories configuration
profiles.yml        Deployment profiles (production, staging, minimal, dev)

Setup

Prerequisites

• A Linux VPS with systemd, python3.11+, sqlite3, git, gh (GitHub CLI)
• A GitHub account with a fine-grained PAT (repo, issues, pull_requests, workflows)
• An AI provider API key (Claude/Anthropic or compatible endpoint)
• Optional: Feishu/Lark or Telegram for notifications

Quick start

1. Clone this repo to your VPS:

   gh repo clone YOUR_ORG/claude-bot /srv/claude-bot-src

2. Configure — copy and fill in the env file:

   cp claude-bot.env.example /etc/claude-bot/claude-bot.env
   $EDITOR /etc/claude-bot/claude-bot.env

   At minimum set: GH_TOKEN, SELF_FIX_REPO, ALERT_REPO, SELF_INTROSPECTION_REPO, TRUSTED_BOT_LOGINS, and your AI provider credentials.

3. Configure repos — edit repos.yml to list the repositories you want the bot to monitor. See the file for the format.

4. Deploy:

   VPS=user@your-vps-host ./deploy.sh

5. Check status:

   systemctl status claude-scheduler claude-worker@1
   journalctl -u claude-worker@1 -f

Labeling issues

Add the claude label to any GitHub issue in a registered repository. The bot will pick it up within POLL_INTERVAL seconds (default: 120).

Additional labels:

• claude-hard — use the stronger/more expensive model tier
• claude-ultracode — use maximum-effort mode (token-expensive)
• claude-no-automerge — implement and open a PR, but do not auto-merge
• claude-docs — documentation-only change

Environment variables

See claude-bot.env.example for all configurable variables with descriptions. The most important ones:

Variable	Required	Description
GH_TOKEN	Yes	GitHub fine-grained PAT
SELF_FIX_REPO	Yes	Repo where the bot files self-fix issues
ALERT_REPO	Yes	Repo where the watchdog posts alerts
SELF_INTROSPECTION_REPO	Yes	Repo for the self-introspection patrol
TRUSTED_BOT_LOGINS	Yes	Your GitHub login (comma-separated)
ANTHROPIC_AUTH_TOKEN	Yes	AI provider API key
ANTHROPIC_BASE_URL	Yes	AI provider base URL
PROVIDER	Yes	Provider identifier (see provider.py)

Known limitations / bugs

• The Feishu/Lark integration (feishu_bot.py) requires manual REPO_ALIASES configuration for issue routing.
• The self-update deploy gate can be overly conservative — use touch /srv/claude-bot/watchdog/self-update.urgent to force a deploy.
• Cross-repo patrol requires ORG_COHERENCE_ORG to be set and a GitHub org with visible repos.
• The bot runs as root in the reference deploy (see deploy.yml); for production use, create a dedicated low-privilege user and adjust ReadWritePaths in the systemd units.
• Test coverage is good for core scheduling/worker paths but thin for the self-update and Feishu integration.

Philosophy

See docs/philosophy.md for the design rationale.

License

MIT