Skip to Content
Getting Started

Getting Started

Which ShipCode do I need?

ShipCode is two separate products that share the same pipeline engine. Pick one:

  • Desktop App — full Electron GUI (Overview, Inbox, Automations, project tabs, Terminal drawer, Settings, Plan Viewer). Use this if you want to watch pipelines run, triage issues, schedule work, and review plans visually.
  • CLI — headless shipcode command. Use this for terminal-first workflows, CI automation, cron jobs, or server environments without a display.

Both read the same SQLite DB and worktree layout, so you can install both and they stay consistent.

Prerequisites

Desktop App

brew tap shipshitdev/tap
brew install --cask shipcode

Launch ShipCode from Applications. First run opens the onboarding wizard, which doctor-checks the prerequisites above and walks you through adding your first repository.

CLI Quick Start

# Run once without installing
npx @shipshitdev/shipcode onboard
npx @shipshitdev/shipcode run <issue-number>
 
# Or install globally so the `shipcode` command is always on your PATH
npm install -g @shipshitdev/shipcode
shipcode onboard
shipcode run <issue-number>

The package is published as @shipshitdev/shipcode. The bin name stays shipcode, so npx @shipshitdev/shipcode, npm install -g @shipshitdev/shipcode, then shipcode ....

Adding a Repository

  1. Click + Add Repository in the sidebar
  2. Select your project directory
  3. ShipCode detects git remote and default branch automatically
  4. Open Project Settings to configure setup, verification, runtime QA, GitHub Projects sync, and any project-level model overrides

Starter issue

When the repository is connected to GitHub, ShipCode seeds one starter issue named Ship your first change with ShipCode. The issue asks for a tiny, low-risk change so you can run the full loop without inventing a first task.

ShipCode records the starter issue number on the project. If you import the same GitHub repo again, it reuses that metadata instead of creating another starter issue.

Your First Pipeline

  1. Open the project — Issues is the default project tab and contains the Kanban Board
  2. Click Refresh to load GitHub issues, or create a PRD from the app
  3. Drag an issue from Backlog to Planning, or use auto-run from the board header
  4. Watch the pipeline run: Plan → Review/Revisions → Execute → Test/Runtime QA → Verify → Ship — output streams into the Terminal drawer
  5. When the pipeline finishes, ShipCode opens the PR and links it back to the issue; Overview and Activity show the completion

Next steps

  • Desktop App overview — tour of the main views
  • Configuration — GitHub label conventions and status-label mapping
  • OpenRouter — how to run the pipeline with OpenRouter models
  • CLI — headless version for terminal-first workflows
Last updated on
IntroductionArchitecture