Introduction

Shipper is a workflow orchestrator for GitHub-hosted repositories. It is not a coding agent. It keeps a Shipper issue moving through product grooming, design, planning, implementation, PR review, Rework when feedback requires changes, and merge while the configured agent does the stage work. That sequence is not fixed: design assigns each issue a route, and a simple-route issue is implemented directly from its design, skipping planning and the separate implementation stage. The State Machine page covers both routes.

Workflow identity, stage, priority, failed state, and issue title/body content live in the local issue-state store. When issue projection is enabled, Shipper mirrors workflow labels, fitted issue content, and workflow comments to GitHub for human review and integrations. Workflow events carry stage summaries and other run artifacts: grooming summaries, technical designs, implementation plans, review output, and implementation summaries. Shipper reads the current state, chooses the next command, creates the work context, and expects the agent to report a verdict through the stage contract.

You can run Shipper through the npm CLI or the supported macOS desktop app. Both entry points use the same local issue-state records, locks, settings, and workflow artifacts, with GitHub issue mirrors and comments present only when projection is enabled. Teams can move between terminal workflows and the desktop pipeline board without changing project state.

Start with Getting Started for CLI setup or the Desktop guide for desktop setup. Read Architecture for the runtime tour, State Machine for label behavior, and Protocol for the agent contract.