Shipboard

Know what needs to happen next across your repositories.

Shipboard is a local delivery tracker for developers working with coding agents. It connects related pull requests into one work item and follows them from local changes through review, merge, deployment, and testing. A CLI, browser dashboard, and MCP server share the same SQLite database, so Claude Code and Codex can pick up where you left off.

Shipboard derives what it can from GitHub. You and your agents add the context GitHub doesn't have: the objective, merge dependencies, verification, and release chores.

• One feature, several repos: group PRs and record the order they need to merge.

• A next-action queue: surface review feedback, failing CI, unpushed work, and outstanding tasks with reasons for each suggestion.

• Portable handoffs: resume with the objective, worktree paths, commits, recent notes, and remaining actions.

• Evidence tied to commits: changes to linked PRs invalidate old test and manual deployment confirmations.

• Local worktree tracking: find forgotten branches and inspect cleanup candidates.

Shipboard is early-stage software. Its review pipeline currently expects configured review bots, and its development-stage model assumes the development branch reaches your dev environment. See configuration for the assumptions and optional integrations.

Quickstart

1. Install from source

You'll need Node.js 22.12+, npm, Git, and an authenticated GitHub CLI with access to the repositories you track. macOS is the primary development platform; built-in scheduling and --open use macOS utilities. On other platforms, open the dashboard URL yourself and use your own scheduler.

Clone this repository and install from its root:

git clone https://github.com/CharlieHorton/shipboard.git
cd shipboard
npm ci
npm link
shipboard --help
gh auth status

npm ci builds the three entry points in dist/. npm link puts shipboard, shipboard-mcp, and shipboard-hook on your PATH. To skip linking, use node /absolute/path/to/shipboard/dist/cli.js wherever these docs say shipboard. If GitHub CLI isn't signed in yet, run gh auth login.

2. Configure your repositories

Point Shipboard at a local checkout of a project you want to track:

shipboard project add my-project --local /absolute/path/to/your-repo

Or run shipboard project add my-project from inside that checkout. Shipboard reads its GitHub origin, finds the main checkout, and saves the configuration in ~/.shipboard/config.json. It prints the selected branches and deployment mode so you can check them. No fetch or sync runs during setup.

For an explicit development/production workflow:

shipboard project add my-project --local /absolute/path/to/your-repo \
  --dev-branch develop --prod-branch main --deploy manual

For GitHub tracking without a local checkout:

shipboard project add my-project --repo your-org/your-repo \
  --dev-branch develop --prod-branch main

Repeat with the same project name and a different repo to group related repositories. Repeat with a new name to add another project. Existing settings are preserved; already registered repositories are refused rather than replaced. Restart a running dashboard or MCP server after adding repositories.

By default, production uses the cached origin/HEAD, then a local or cached main/master branch, then main. Development uses develop if found, otherwise the production branch. Deployment defaults to manual. With --repo alone, both branches default to main. Override these options to match your workflow. See configuration for advanced settings and the example JSON for manual editing.

3. Sync and open the dashboard

shipboard sync
shipboard serve

Open http://127.0.0.1:7373. On macOS, shipboard serve --open opens it for you. Unlinked PRs appear after syncing; create an item to group a feature's work:

shipboard item add --project my-project --title "Add search" \
  --summary "Let users search their saved documents." \
  --change "Add a search endpoint and results page"

# Use the item ID printed above and an existing PR number.
shipboard link 1 'your-org/your-repo#42'
shipboard task add 1 --kind test "Verify search on dev"
shipboard next
shipboard resume 1

Related MCP server: Memory MCP

Connect your coding agent

Both agents use the same local stdio MCP server. Run these from the Shipboard checkout after installation:

Claude Code

claude mcp add --transport stdio --scope user shipboard -- node "$PWD/dist/mcp.js"
claude mcp get shipboard

Codex

codex mcp add shipboard -- node "$PWD/dist/mcp.js"
codex mcp get shipboard

Start a new agent session, then ask: “Use Shipboard to show what needs my attention.” Complete the agent setup guide to add workflow instructions, Claude Code's optional hooks, and desktop PATH configuration. The guide also covers other agents that support local stdio MCP servers.

Everyday commands

Run shipboard <command> --help for options. Usage details explain source freshness, worktree removal, and when verification needs repeating.

Data and access

Data lives in ~/.shipboard/: config.json, shipboard.db, and optional sync logs. SHIPBOARD_HOME selects another data directory; SHIPBOARD_DB overrides the database path. GitHub access uses your existing gh authentication. Optional EAS integration invokes your authenticated eas CLI. Local worktree sync runs git fetch in configured checkouts.

The dashboard is intended for a single user on localhost and has no login system. Keep its default loopback binding. MCP tools can update tracker records and run sync; the dashboard can remove a worktree after confirmation and local checks. It does not merge PRs or deploy applications for you. See the security policy for the trust boundary and reporting guidance.

Development and license

npm run typecheck
npm test
npm run build

See CONTRIBUTING.md for development setup and docs/design.md for architecture and design history. Release notes live in CHANGELOG.md. Rebuild after pulling updates; the CLI, hooks, and MCP server run from dist/.

MIT licensed.