forge-registry

Builds the global, opt-in, read-only Forge Project Registry across all projects. Use when the owner wants a bird's-eye view of status, last run, tickets, and ports.

SKILL.md

GitHub

forge-registry — global project registry (opt-in, read-only)

An opt-in aggregate across every Forge project on this machine. It never runs automatically and never changes any project — it only reads and writes one global index.

When to use

  • The owner asks "show me all my Forge projects" / "which projects have open tickets / failing tests".
  • Before a portfolio-wide sweep, to see status/ports/last-run at a glance.

How to run

node .claude/forge-bin/forge-registry.cjs scan            # scan ~/Documents, write the registry
node .claude/forge-bin/forge-registry.cjs scan --json     # also print the aggregate to stdout
node .claude/forge-bin/forge-registry.cjs scan --root <dir> --run <run_id>

Outputs (global):

  • ~/.claude/forge/registry/projects.json — machine-readable index.
  • ~/.claude/forge/registry/index.html — a self-contained home-view (open it directly in a browser; data is inlined, no server needed).

Each record: project_id, name, path, stack, status, last_run_id, last_run_status, last_run_at, open_tickets, test_status, port. test_status reads a run's doctor.json (from Forge Doctor) when present.

Hard rules (isolation + honesty)

  • Reads other projects' .claude/ read-only (that is the opt-in aggregation job); it NEVER writes into any scanned project. The only thing written is the global registry dir.
  • Every record is secret-redacted before writing (defense in depth) — never persists a raw key.
  • Real DASHBOARD_STATE.json / run.json data only; a missing/malformed file yields honest defaults (unknown), never a fabricated status. (: the retired per-project server.cjs that used to write DASHBOARD_STATE.json is removed, so a project synced since then will simply never have one — the same honest-default path a project that never started that old dashboard already went through.)
  • Opt-in only: it never runs on require, only via the scan command.