reef

name	reef
description	Launch the coral-reef dashboard (auto-install, build, and start)
argument-hint	[--rebuild]

Coral Reef Dashboard

ARCHIVED — not a live skill. Moved out of skills/ so it is not discovered or exposed to users (Claude Code recursively registers every skills/<name>/SKILL.md; there is no frontmatter/naming flag to hide one in place). coral-reef development is paused. To re-enable: move this directory back to skills/reef/. Note the data dir (~/.claude/coral-reef/) still hardcodes ~/.claude and does not yet honor CLAUDE_CONFIG_DIR — fix that in the coral-reef server repo before re-enabling.

Launch the coral-reef dashboard. Handles installation, updates, builds, and startup automatically.

The runtime injects Base directory for this skill: which resolves to this skill's installed path. From there, the plugin root is two levels up, and coral-reef/ sits as a sibling directory.

Constants

REPO_URL = "https://github.com/kangig94/coral-reef"
REEF_DATA_DIR = ~/.claude/coral-reef/
REEF_PORT = 3100

Protocol

Step 1 — Resolve Paths

Derive the plugin root from the base directory injected by the framework:

PLUGIN_ROOT = resolve(base_directory, "../..")
REEF_DIR = resolve(PLUGIN_ROOT, "coral-reef")

Verify PLUGIN_ROOT contains package.json with "name": "coral" as a sanity check.

Step 2 — Ensure Data Directory

mkdir -p ~/.claude/coral-reef

This is coral-reef's permanent SQLite storage location, surviving /tmp reboots.

Step 3 — Clone or Update

Check if REEF_DIR exists:

• Not exists: git clone ${REPO_URL} ${REEF_DIR}
• Exists with .git/: cd ${REEF_DIR} && git pull --ff-only
• Exists without .git/: warn user and skip update (manual install)

Step 4 — Dependency Resolution

Detect the install layout by checking if this is a nested plugin install or a dev workspace:

# Read coral-reef's package.json
cd ${REEF_DIR}

Check if the coral dependency in package.json points to the correct location:

• Dev workspace layout (~/workspace/coral-reef sibling to ~/workspace/coral): The coral dependency should be "file:../coral". Leave as-is.

• Nested plugin install (${PLUGIN_ROOT}/coral-reef/ inside ${PLUGIN_ROOT}/): The coral dependency should be "file:.." (parent is the plugin root = coral itself). If it currently says "file:../coral", rewrite it to "file:..".

Rewrite logic (only when nested):

# Read package.json, replace "file:../coral" with "file:.." in the coral dependency

Use jq or a JSON-safe read/write to avoid breaking package.json.

Step 5 — Install and Build

cd ${REEF_DIR}
npm install
npm run build

If --rebuild argument is provided, always run the full install + build even if node_modules/ exists.

If no --rebuild and node_modules/ exists and bridge/ (build output) exists, skip install/build and go straight to start.

Step 6 — Start Server

Check if coral-reef is already running on port 3100:

curl -s http://localhost:3100/api/system/health

• Already running: inform user, skip to Step 7
• Not running: start in background:

  cd ${REEF_DIR} && node dist/server/index.js &
  

  Wait up to 5 seconds for the health endpoint to respond.

Step 7 — Open Browser

open http://localhost:3100  # macOS
xdg-open http://localhost:3100  # Linux

Report the dashboard URL to the user.

Error Handling

Scenario	Action
git clone fails	Report error with URL, suggest manual clone
git pull --ff-only fails	Warn about local changes, suggest --rebuild after manual resolution
npm install fails	Show error output, check if coral dependency path is correct
npm run build fails	Show error output, suggest --rebuild to retry clean
Port 3100 in use by non-reef process	Warn user, show what's on the port
PLUGIN_ROOT sanity check fails	Error: cannot determine coral plugin root

Notes

• The dashboard data persists at ~/.claude/coral-reef/db.sqlite across sessions
• The server connects to the coral backend via SSE for live updates
• If the coral backend is not running, the dashboard still shows historical data from SQLite
• Use --rebuild to force a clean install + build (useful after coral updates)