Shippy

Assign a GitHub issue, wake up to a PR.

Shippy is an autonomous agent that runs on a VPS and ships code for you. Assign an issue to the agent's GitHub account, and it creates a pull request with the implementation.

~630 lines of bash. No frameworks, no Docker, no API keys — just cron, flock, and git worktrees on a $10/month VPS.

Agents

Issue Worker — Picks the oldest assigned issue across all repos, creates a feature branch, implements the changes using Claude Code, and opens a PR.

Feedback Worker — Runs every 5 minutes. Watches for @mentions on PRs created by the issue worker. When a reviewer leaves feedback, it implements the requested changes and pushes.

Setup

Prerequisites

• Linux VPS (uses /proc/meminfo for memory checks)
• Claude Code CLI, authenticated
• GitHub CLI authenticated as the agent account
• A GitHub account for the agent (e.g. my-bot) added as collaborator to target repos

Install

git clone git@github.com:yourname/Shippy.git ~/projects/shippy
cd ~/projects/shippy
bin/deploy

Configure

Create ~/shippy/.env:

AGENT_GITHUB_USERNAME=my-bot
AUTHORIZED_USERS=yourname,teammate

# Optional — Telegram notifications (omit to disable)
TELEGRAM_URL=https://api.telegram.org/bot<token>/sendMessage
TELEGRAM_CHAT_ID=<chat-id>
TELEGRAM_TOPIC_ID=<topic-id>

Variable	Description
AGENT_GITHUB_USERNAME	GitHub username of the agent account
AUTHORIZED_USERS	Comma-separated GitHub usernames allowed to trigger the feedback worker via @mentions
TELEGRAM_URL	Optional. Telegram bot API URL. Omit to disable notifications.
TELEGRAM_CHAT_ID	Telegram chat/group ID to send messages to
TELEGRAM_TOPIC_ID	Optional. Forum topic ID for threaded groups

Cron

# Poll for PR feedback (every 5 min, cheap when idle)
*/5 * * * *     ~/shippy/feedback-worker.sh

# Poll for assigned issues (every 5 min, offset by 1 min to avoid flock collision)
1-59/5 * * * *  ~/shippy/issue-worker.sh

# Priorities / self-directed for specific repos (once daily, offset to avoid flock collision)
1 6 * * *       ~/shippy/issue-worker.sh yourname/your-repo

Usage

1. Invite the agent account as a collaborator on your repo
2. Assign a GitHub issue to the agent
3. Within 5 minutes, Shippy picks it up and creates a PR
4. Review the PR — @mention the agent for feedback, it responds automatically

Issue Worker Modes

Without arguments — polls for assigned GitHub issues across all repos. If no issues are assigned, exits cleanly (no Claude invoked). Run every 5 minutes.

~/shippy/issue-worker.sh

With a repo argument — works on a specific repo using priorities or self-directed mode. Run once daily per repo:

~/shippy/issue-worker.sh owner/repo

Task priority in repo mode:

1. priorities.md — First item from <project>/.shippy/priorities.md. Skipped if 2+ Shippy PRs are open.
2. Self-directed — Analyzes the codebase for the highest-impact small improvement. Same PR limit.

Notifications

Shippy sends Telegram messages when:

• A PR is created (with title, summary, and link)
• A PR feedback comment is addressed
• An error occurs (timeout, forbidden files, failures)
• Too many open PRs are blocking repo-mode runs

Telegram is optional. If TELEGRAM_URL is not set in .env, notifications are silently skipped and everything else works normally.

Contributing

See CLAUDE.md for project conventions.