Prerequisites

Shipyard is a native macOS application. Before installing, make sure you have:

• macOS
• Node 22+
• Docker Desktop with the docker sandbox plugin
• VS Code's code command on PATH (for Open in Editor)
• A local git repo checkout

Installation

Clone the repo and install dependencies:

git clone https://github.com/arthur791004/calypso-multi-agent.git
cd calypso-multi-agent
npm install

Start the development server:

npm run dev

This launches both the backend (:9090) and frontend (:9091) via npm-run-all. Open http://localhost:9091 to get started.

First Run

On first launch, Shipyard shows a Welcome screen that asks you to pick a repo folder. It gets symlinked to .config/repo/<name>/<default> (no clone), and its trunk branch starts automatically.

Once running:

• Click any task row to open its terminal
• Right-click a task for Copy Name, Open Issue, Preview, Open in Editor, and Delete
• Type / in the composer to get the command palette
• The bottom-right shows n/cap running — turns orange when full

Tasks & Sandboxes

Every row in the task list is a session. Trunk is always the first row with a Dashboard badge. All other tasks run in isolated Docker sandbox containers with Claude Code inside.

Trunk runs on the host (not in a sandbox) for direct access to your real Claude config. The idle sweeper and concurrency cap both skip trunk.

Each sandbox gets its own git worktree. Credentials from ~/.claude-sandbox/ are synced into every sandbox so one login covers all of them.

Slash Commands

Type / in the composer at the bottom of the task list to open the command palette:

/branch <name> [base]

Create a blank sandbox on a new or existing branch. Optionally specify a base branch.

/branch fix-navbar main

/gh-issue <url>

Derives a branch name from the GitHub issue number, creates it, and seeds Claude with a prompt to implement the issue.

/gh-issue https://github.com/org/repo/issues/123

/linear <url>

Derives the branch name from the Linear ticket identifier and seeds Claude with the ticket context.

/linear https://linear.app/team/issue/PROJ-456

Terminal Panel

Click any task to open the terminal panel on the right. It has three tabs:

• Claude — live Claude Code agent output
• Terminal — shell access to the sandbox
• Logs — dashboard dev server logs

The status bar at the bottom shows the current sandbox state: Creating, Starting, Running, Stopped, or Error. Action buttons in the header provide quick access to Preview, Open in Editor, and Fullscreen.

Repo Settings

Click the gear icon to open Settings. Each repo can override:

• Install command — runs in each worktree before the dev server. Default: yarn install
• Start command — dev server launcher. Default: yarn start-dashboard. Invoked as PORT=<port> <cmd>
• Preview URL — opened when you click Preview. Default: http://my.localhost:3000

Environment Variables

Configure Shipyard behavior with environment variables:

MAX_SANDBOXES=9          # Concurrency cap for docker sandboxes
SANDBOX_IDLE_MS=1800000  # Idle timeout before auto-stop (30 min)
SANDBOX_IDLE_CHECK_MS=60000  # Sweeper tick interval
DATA_DIR=.config         # Where state.json and sessions.jsonl live
DOCKER_IMAGE=claude      # Docker image used for sandboxes

Electron App

Run Shipyard as a native desktop app:

npm run electron:dev

This compiles the Electron main process and opens a native window. If npm run dev is already running, Electron attaches to those servers instead of spawning duplicates. Otherwise it launches backend + Vite as child processes and shuts them down on quit.