Harbormaster

Stop cd-ing between projects. One MCP server routes any question to any project's subagent — locally or over SSH — with a live operator dashboard for the whole fleet.

Harbormaster is a Model Context Protocol (MCP) server + operator console for developers who work across many projects at once. Point your Claude Code, Claude Desktop, Codex, Cursor, or any MCP client at it, and you can ask any project a question — without cd — and the target project's subagent loads its own CLAUDE.md and Serena memories, answers, and returns a summary.

The bundled web dashboard turns the same server into a glanceable mission control: a project grid with KPIs, an inter-project network graph, a live dispatcher trace waterfall, a markdown memory editor, multi-axis budgets (per-host / per-tool / per-project), and a light/dark theme.

Part of the FleetQ ecosystem. Standalone OSS works fully without FleetQ; FleetQ Bridge integration is purely additive.

---

Why Harbormaster?

You probably already have:

• 5–80 projects in ~/htdocs/ (or ~/work/, or ~/code/)
• Each with its own CLAUDE.md, Serena memories, framework, Git state
• Possibly 1–5 SSH-reachable VPS hosts running production copies
• One LLM-coding session per project (Claude Code, Codex, Cursor) — which means context-switching costs every time you cd somewhere new

Without Harbormaster: You change directory, wait for the agent to re-bootstrap context, ask the question, copy the answer back. Repeat 12 times a day.

With Harbormaster:

> ask_project "accounting-fleetq" "did the cron job run today?"
> fan_out_ask "any flaky tests since last release?" --hosts=local,prod-1
> delegate_task "hr-fleetq" "summarize last 10 commits" --deliverable=changelog

The calling session never leaves its own cwd. The target project's subagent loads its own memory, answers, returns a summary, and your question + answer go into a recall-able Q&A history.

Who is this for?

| You are… | And Harbormaster gives you… | |---|---| | A solo developer with 10+ side projects | One console for all of them, with cross-project search and a graph of who calls whom | | A small-team CTO | One MCP endpoint your agents talk to across local + production hosts, with budget caps per host/tool/project | | A platform engineer | A drop-in Bridge daemon for FleetQ — Platform Tool, A2A Agent Cards, federated KnowledgeGraph | | An AI agent researcher | A real-world multi-agent orchestration target with a working web UI for observability | | A vibe coder with too many tabs | A keyboard-first dashboard (Cmd-K palette, 1–5 tab nav) and a calmer life |

---

What it does

You work across many projects, each with its own CLAUDE.md and Serena memories. Switching cwd loses context. Harbormaster lets one Claude Code (or Codex) session ask any project a question without changing directory — the project's subagent loads its own memory, answers, and returns a summary.

Eight MCP tools cover the day-to-day flow: list projects and hosts, inspect project status, ask a single project, fan out to many, recall prior Q&A, walk the inter-project dependency graph. Optional SSH fan-out targets remote VPS hosts. Optional FleetQ adapter exposes Harbormaster as a first-class Bridge daemon (Platform Tool, A2A Agent Cards, federated KnowledgeGraph).

The companion web UI turns the same MCP server into a local operator console: dashboards, trace waterfall, network graph, memory editor.

---

Quick start

Install with the [ui] extra so you also get the operator dashboard:

uvx --prerelease=allow 'harbormaster-mcp[ui]' --version
# or with pipx:
pipx install --pip-args='--pre' 'harbormaster-mcp[ui]'

Register in Claude Code:

claude mcp add --scope user harbormaster harbormaster-mcp

Or in Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "harbormaster": {
      "command": "/opt/homebrew/bin/harbormaster-mcp",
      "env": {}
    }
  }
}

Run the operator UI alongside (separate process — both read the same TOML config so projects discovered by one are visible to the other):

export HARBORMASTER_UI_TOKEN=$(python -c 'import secrets; print(secrets.token_urlsafe(32))')
harbormaster-ui --port 7531
# then open http://127.0.0.1:7531/ — paste the token at the prompt

Zero-config by default: Harbormaster auto-discovers projects under ~/htdocs/* if it exists. For any other layout, see Configuration.

---

Tools

Twelve MCP tools, all optionally targetable at a remote host via host="<label>".

| Tool | Purpose | Cost | |---|---|---| | list_projects(host=None) | Enumerate configured projects (local) or remote dir listing (SSH). | ~50 ms / ~1 s | | list_hosts() | Configured [hosts] plus ~/.ssh/config Host aliases. | ~5 ms | | project_status(name, host=None) | Git log, Serena memory list, log tails. | ~200 ms / ~2 s | | ask_project(name, question, max_turns=5, host=None) | Spawn claude -p (or configured backend) in project cwd, return ≤ 800-word summary. | ~30 s / ~90 s | | delegate_task(name, task, deliverable, allow_writes=False, mode="sync", inbox_id="default", host=None) | Delegate a task; allow_writes=true lets the subagent edit files directly, false (default) keeps it read-only. mode="async" enqueues and returns immediately; the caller polls with get_delegated_task or drains the inbox with recall_pending_results. | sync: ~60 s / async: ~5 ms enqueue | | get_delegated_task(job_id) | v22.0.0 — status of one async delegated job. | ~5 ms | | recall_pending_results(inbox_id, mark_read=True, limit=50) | v22.0.0 — drain completed/failed async jobs from one inbox (FIFO on completion). | ~10 ms | | await_delegated_task(job_id, timeout_seconds=900) | v22.1.0 — block until one specific job lands. Returns immediately if already done; on timeout returns the current row with status="running" or "queued". | up to timeout_seconds | | await_inbox(inbox_id, timeout_seconds=900, since=None) | v22.1.0 — block until ANY job in the inbox lands. since skips completions already seen. Caller drains via recall_pending_results after. | up to timeout_seconds | | fan_out_ask(question, project_filter=None, host_filter=None, max_concurrency=5, max_turns=3) | Parallel multi-project Q&A; one section per target. | ~max_turns × backend_time × ⌈targets / max_concurrency⌉ | | recall_qa(question, top_k=5, host=None, project=None, min_similarity=0.6) | Semantic recall over prior Q&A answers. Opt-in via [history] enabled = true. | ~50 ms (FTS5) / ~150 ms (vec, after warm-up) | | project_graph(format="json", include_dev_deps=False, transitive=False) | Cross-project dependency graph from manifest parsing. Returns nodes + edges + optional Mermaid markup. | ~100 ms / ~10 ms cached |

Full design notes for each tool live in docs/architecture-harbormaster.md.

---

UI overview

The companion dashboard (harbormaster-ui --port 7531) is a local-first operator console. All surfaces speak the same SSE event stream that powers the MCP transport, so what you see in the UI matches what your MCP clients see.

Workspace shell (v19+)

Every page renders inside a fixed three-column workspace borrowed in spirit from VSCode / Postman / Linear:

┌─ topbar (h-12, fixed) ────────────────────────────────┐
├──────────┬──────────────────────────┬─────────────────┤
│ sidebar  │ main                      │ inspector      │
│ (240px)  │ (1fr, scroll-y)           │ (320px,        │
│ projects │ page-specific content     │  collapsible)  │
└──────────┴──────────────────────────┴─────────────────┘

• Topbar — brand-mark + page title + Cmd-K hint + theme toggle + auth indicator.
• Sidebar — all hosts ▾ filter + Filter projects… search + RECENTLY ASKED + language groups (GO, JAVASCRIPT, PHP, …) with ★-pinned project markers.
• Main — page content; layout choice (single column / card grid / split pane / tabs) belongs to the page.
• Inspector — context-aware widgets per page (KPI summary + live activity feed on the dashboard, project metadata + budget gauges on the project page, etc.). Collapse via « button (state persisted in localStorage); auto-collapses below 1280 px.

Linear-violet OKLCH palette, compact density, light/dark theme toggle.

Per-page surfaces

• Dashboard (/) — Quick Ask card at the top (project picker + question → navigates to project page with pre-filled query), KPI strip (projects, active embeds, recent queries, bridge state, dispatcher health, host budget headroom), 2-column card grid (recent activity, Auto-reembed, FleetQ Bridge, Plugins, Recall Q&A history full-width, Project graph full-width). Inspector shows a KPI mini-strip plus a live SSE-driven activity feed with pulse-on-new.

• Project page (/projects/<name>) — five-tab system: Overview / Memories / Trajectories / Q&A History / Settings. Number keys 1–5 jump tabs; #tab=<id> URL hash makes shareable deep links. Inspector shows project metadata + 24h budget consumption.

  

• Memories tab — split-pane editor: file list (left) + raw markdown textarea (centre) + bleach-sanitised live HTML preview (right). Toolbar: Save / Undo (Cmd-Z) / Redo (Cmd-Shift-Z) / diff vs: revision selector. Last-20 per-file history, side-by-side HTML diff, optional tag chip editor.

  

• Network (/network) — inter-project call graph rendered with a vendored Cytoscape build. Edge weights track real Harbormaster MCP calls (caller → target). Filters by host / project / tool / window; switchable graph / chat list view; SSE-driven live append. Aggregate stats at /api/network/stats?window=….

  

• Dispatcher trace (/dispatcher) — live in-flight spans + last-100 completed spans rendered as a waterfall with parent / child nesting. Each span exposes tool, project, host, duration, and (where the backend emits it) tool-call sub-spans for the model's own tool use. Real backend token usage in the SSE usage event.

  

Mobile (< 1024px)

Below 1024px the 3-column shell collapses into drawers. A hamburger (☰) toggles the sidebar; an info button (ⓘ) toggles the inspector. Click the backdrop or press Esc to dismiss.

<table> <tr> <td><img src="docs/screenshots/dashboard-mobile.png" alt="Mobile dashboard — drawers closed, hamburger + info buttons in topbar" wid