Shipyard

Why Shipyard?

Development work is spread across editors, terminal windows, Git clients, task boards, and AI tools. Shipyard brings the operational layer together without trying to replace your editor.

• Local-first — the dashboard and API run on your machine; project and task data stays in local JSON files.
• Portfolio view — see every project, active task, branch, and working tree from one place.
• Fast project switching — keep multiple workspaces open with responsive tabs and an overflow menu.
• Built for AI-assisted development — launch Claude Code with project/task context or expose Shipyard through MCP.
• No database required — installation, backup, inspection, and recovery remain straightforward.
• Cross-platform — desktop installers for Windows, macOS, and Linux, plus browser-based development mode.

Highlights

A terminal designed for AI workflows

The integrated terminal includes WebGL rendering, output batching, safe bracketed paste, reconnect handling, split panes, and session persistence. Clipboard images can be pasted with Ctrl+V: Shipyard stores the image temporarily on your machine and inserts its path into the Claude Code prompt.

Minimal, scalable interface

Primary actions stay visible; secondary actions live in contextual menus. Project tabs adapt to the available width instead of introducing horizontal page scrolling, and the active project always remains accessible.

Download

Use the latest CI-built installers from the Releases page.

Release builds support Windows Authenticode signing and macOS Developer ID signing/notarization. Maintainers must configure the repository secrets described in Release signing; unsigned local builds may still show the operating system's security warning.

Run from source

Requirements

• Node.js 20 LTS or newer
• pnpm
• Git

git clone https://github.com/defremont/Shipyard.git
cd Shipyard
pnpm install
pnpm dev

Open http://localhost:5421. The frontend runs on port 5421 and the Fastify API on 5420.

Setup helpers are also available:

# Linux / macOS
chmod +x setup.sh devdash.sh
./setup.sh
./devdash.sh

# Windows
setup.cmd
devdash.cmd

The first-run wizard helps discover project folders and explains the main workspace controls.

Optional integrated terminal

The browser terminal uses node-pty, which is installed as an optional native dependency. If it is unavailable, the rest of Shipyard continues to work and terminal actions fall back to native operating-system terminals.

Core workflows

Manage projects

Add existing folders or scan a parent directory. Shipyard detects Git repositories, common technologies, branches, local changes, remotes, and one-level nested repositories. Favorite important projects or jump to any workspace with Ctrl+K.

Plan and execute tasks

Each project has a virtual General milestone and can define additional milestones. Tasks move through Inbox, In Progress, and Done while preserving cascading timestamps. The description captures the product outcome; the technical prompt captures implementation context for a developer or coding agent.

Work with Git

Inspect changes, review diffs, stage files, commit, synchronize with remotes, and browse history without leaving the workspace. Projects containing multiple independent repositories expose repository tabs and keep query state isolated per repository.

Use Claude Code

Shipyard is CLI-first. Server-side AI features prefer the existing Claude Code OAuth session, then the local Claude CLI, and finally a configured API key. You can:

• open Claude Code in a project terminal;
• resolve one task with generated project context;
• organize or update multiple tasks from natural language;
• analyze tasks and generate implementation prompts;
• generate commit messages from the current diff;
• paste text or clipboard images into the integrated terminal.

AI features are optional; project, task, Git, file, and terminal management work without them.

Connect through MCP

Shipyard includes a Model Context Protocol server with OAuth 2.1 and PKCE. Compatible agents can list projects and milestones, create or update tasks, inspect Git state, reorder work, and trigger configured sync providers. Connection instructions and consent controls are available under Settings → MCP.

Synchronize milestones

Integrations are isolated by (project, provider, milestone), so each milestone can connect to a different remote board, list, or sheet.

Credentials are configured once per provider; mappings and synchronization state remain local. Detailed setup guidance is built into Shipyard's Help and Settings pages.

Keyboard shortcuts

On macOS, use Cmd for application shortcuts where applicable.

Data and privacy

Shipyard does not require a Shipyard account or hosted database.

In development mode, data is written under data/. Desktop builds store it in the operating system's application-data directory. The main files are plain JSON and can be backed up with normal filesystem tools.

data/
├── projects.json
├── settings.json
├── tasks/
│   └── <projectId>.json
├── sync-config.json
├── mcp-config.json
├── mcp-auth.json
└── server.log

Third-party features communicate only with the provider you configure, such as Anthropic, Google Apps Script, Trello, or ClickUp. Review those providers' privacy policies before enabling an integration.

Architecture

┌─────────────────────────────────────────────────────────────┐
│ React + Vite client                                         │
│ dashboard · tasks · Git · files · terminal · AI · settings │
└──────────────────────────────┬──────────────────────────────┘
                               │ REST / SSE / WebSocket
┌──────────────────────────────▼──────────────────────────────┐
│ Fastify server                                              │
│ routes · services · MCP · PTY · sync adapters · AI backend │
└───────────────┬──────────────────────────────┬──────────────┘
                │                              │
       ┌────────▼────────┐            ┌────────▼────────┐
       │ Local JSON data │            │ Local projects  │
       │ atomic + locked │            │ Git + filesystem│
       └─────────────────┘            └─────────────────┘

Repository layout

client/src/       React application, components, hooks, and API client
server/src/       Fastify routes and domain services
electron/         Desktop process, preload bridge, and packaging hooks
assets/           Icons and README media
data/             Local development data (generated and gitignored)
.github/workflows Release automation for Windows, macOS, and Linux

Development

pnpm dev              # frontend + backend with watch mode
pnpm build            # production client, server, and Electron build
pnpm dist:win         # Windows installer
pnpm dist:mac         # macOS DMGs
pnpm dist:linux       # Linux AppImage and deb

The codebase intentionally avoids a database and keeps its data stores recoverable. Before contributing architecture, route, model, or convention changes, read AGENTS.md.

Contributing

Contributions, bug reports, and focused feature proposals are welcome.

1. Fork the repository.
2. Create a branch from main.
3. Install dependencies with pnpm install.
4. Make a scoped change and update documentation when behavior changes.
5. Run pnpm build and test the affected workflow.
6. Open a pull request explaining the problem, solution, and validation.

UI changes should use the existing design tokens and shadcn/ui primitives. New task mutations must invalidate both project tasks and the global task query. New JSON stores must use serialized mutations and atomic writes.

Release process

Pushing a v* tag starts the GitHub Actions release workflow. It builds Windows, macOS Intel/Apple Silicon, AppImage, and Debian artifacts, then creates a draft GitHub release with generated notes and attached installers.

Release signing

For Windows, add WIN_CSC_LINK (a path/URL or base64-encoded PFX) and WIN_CSC_KEY_PASSWORD as GitHub Actions secrets. An OV certificate identifies the publisher but can still need time to build SmartScreen reputation; an EV certificate provides immediate reputation. Keep the certificate subject stable between releases.

For macOS, add MAC_CSC_LINK, MAC_CSC_KEY_PASSWORD, APPLE_API_KEY (the base64-encoded contents of the .p8 key), APPLE_API_KEY_ID, APPLE_API_ISSUER, and APPLE_TEAM_ID. The certificate must be a Developer ID Application certificate for direct DMG distribution. The build uses Hardened Runtime, submits it to Apple for notarization, and staples the resulting ticket.

The application ID (com.shipyard.dev), product name, executable name, and Linux desktop filename are intentionally stable. Changing one of them is a migration and can break Windows taskbar pins, macOS preferences, Linux launcher association, or the upgrade path.

License

Shipyard is available under the Apache License 2.0.

If Shipyard improves your development workflow, consider starring the repository or sharing what you build with it.