Dock

Personal developer dashboard — a lane-based launch board for local projects. Add project shortcuts, organize them in Kanban lanes, and open editors with one click.

Prerequisites

• Node.js 20+
• macOS with Cursor and/or VS Code installed (URL scheme handlers registered)
• For Finder and Terminal launch: install the bundled URL handler app (see below)

Setup

npm install
npm run dev

Open http://localhost:5173 in your browser.

URL handler (one-time, Finder + Terminal)

Browsers block direct file:// navigation, so Finder and Terminal cards use custom URL schemes (dock-finder://, dock-terminal://) handled by a small macOS app. Install it once:

npm run install:handler

This copies a fresh handler into ~/Applications/DockTerminalHandler.app and registers both dock-finder:// and dock-terminal://. Re-run after updating the repo handler (e.g. after npm run build:handler).

If schemes still fail after install, open the handler once:

open ~/Applications/DockTerminalHandler.app

After install, verify registered schemes:

npm run verify:schemes

You should see lines containing cursor:, vscode:, dock-finder:, and dock-terminal:. If Finder or Terminal still fail, rebuild and reinstall the handler (the native Swift binary must match source):

npm run build:handler && npm run install:handler

Usage

1. Add lanes to group projects (e.g. Active, Side Projects).
2. Add project cards with name, absolute path, and launch target (Cursor, VS Code, Finder, or Terminal).
3. Click a card to open the project via URL scheme.
4. Drag lanes horizontally and cards vertically or across lanes.
5. Use Settings to export/import board JSON or set a default launch target.

Scripts

Command	Description
npm run dev	Start web app in development
npm run build	Build web app for production
npm run start	Preview production build
npm run build:handler	Sync handler source into tools/dock-terminal-handler.app
npm run install:handler	Install handler to ~/Applications and register URL schemes
npm run verify:schemes	Check that Cursor, VS Code, and Dock handler schemes are registered

Data

Board state is stored in browser localStorage under dock:v1:board with schemaVersion: 3. v1 and v2 data is migrated automatically on load. Export regularly from Settings for backup.

Architecture

apps/web   → React SPA (lane board, cards, URL scheme launch)
tools/     → URL handler app source + pre-built bundle (dock-finder://, dock-terminal://)

No local server required. The browser navigates to URL schemes when you click a project card.

Limitations

• Finder and Terminal launch require one-time handler install (see Setup)
• Cannot detect whether the target app actually opened after click
• macOS-focused; URL schemes may differ on other platforms