autoship

AutoShip

Install • Docs • Wiki • Commands • Runtime • Testing • Sponsor

Turn backlog into reviewed PRs.

AutoShip is the multi-runtime plugin for solo maintainers who want their GitHub issue queue planned, routed, verified, and packaged into pull requests without babysitting every worker.

┌──────────────────────────────────────────┐
│  ISSUE PLANNING        CONFIGURED ROLE   │
│  MODEL SELECTION       LIVE OPENCODE     │
│  WORKER DISPATCH       15 ACTIVE MAX     │
│  REVIEW                CONFIGURED ROLE   │
│  PR CREATION           CONVENTIONAL      │
├──────────────────────────────────────────┤
│  HERMES RUNTIME        3 ACTIVE MAX      │
│  CRON DISPATCH         AUTONOMOUS        │
│  SUBAGENT POOL         PARALLEL          │
└──────────────────────────────────────────┘

What It Does

• Reads open GitHub issues labeled agent:ready (OpenCode) or autoship:ready-simple (Hermes)
• Plans work in ascending issue-number order
• Dispatches OpenCode workers up to 20 concurrent
• Dispatches Hermes workers up to 20 concurrent via cronjobs
• Verifies completed work before PR creation
• Creates PRs with conventional commit titles
• Tracks local state in .autoship/

Installation

To have OpenCode fetch install instructions directly, tell OpenCode:

Fetch and follow instructions from https://raw.githubusercontent.com/Maleick/AutoShip/refs/tags/v2.2.1/INSTALL.md

Install the CLI globally if you want AutoShip available long-term on your PATH:

npm install -g opencode-autoship
opencode-autoship install
opencode-autoship doctor

For a one-time install without keeping a global CLI, use bunx instead:

bunx opencode-autoship install
bunx opencode-autoship doctor

Then start the setup wizard inside OpenCode:

/autoship-setup

See INSTALL.md for prerequisites, verification, updating, and troubleshooting.

Quick Start

# 1. Install the CLI globally
npm install -g opencode-autoship

# 2. Install AutoShip for OpenCode
opencode-autoship install
opencode-autoship doctor

# 3. Navigate to your project
cd ~/Projects/my-project

# 4. Configure the target repo in OpenCode
/autoship-setup

# 5. Start AutoShip in OpenCode
/autoship

Runtime

AutoShip supports two worker runtimes:

OpenCode (Primary)

OpenCode is the primary supported worker runtime. AutoShip discovers current model availability from:

opencode models

Setup defaults to ranked free worker models from the current OpenCode inventory. On first run, the setup wizard asks which models to use for the orchestrator and reviewer roles; these can be the same model or different models. Operators can explicitly select a comma-separated worker model list with AUTOSHIP_MODELS.

The selected routing is saved to .autoship/model-routing.json. Edit that file manually to tune model eligibility, strength, or task types. Setup preserves manual edits by default; use AUTOSHIP_REFRESH_MODELS=1 bash hooks/opencode/setup.sh to regenerate from the current OpenCode inventory.

Hermes (Secondary)

Hermes is supported as an alternative runtime for autonomous cron-based burn-down. Hermes uses the provider and model configured in ~/.hermes/config.yaml and dispatches work via cronjob or delegate_task.

# Setup Hermes runtime
bash hooks/hermes/setup.sh

# Plan issues for Hermes
bash hooks/hermes/plan-issues.sh

# Dispatch an issue to Hermes
bash hooks/hermes/dispatch.sh <issue-number>