Shippy

# 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](https://docs.anthropic.com/en/docs/claude-code), authenticated
- [GitHub CLI](https://cli.github.com/) authenticated as the agent account
- A GitHub account for the agent (e.g. `my-bot`) added as collaborator to target repos

### Install

```bash
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](CLAUDE.md) for project conventions.