Local dashboard & updates

The local status dashboard is a self-contained HTML page generated on your machine by the context server. It answers, across all editor windows and sessions at once:

• Which prom.codes servers are running right now, where, and in which version — and whether a newer version is published.
• How healthy every locally indexed workspace is: files / symbols / references, embedding coverage %, last index time, DB size.
• What the memory store holds (records by type and scope, recent session captures).
• Whether your setup is sound: awareness hooks installed? API key valid (zero-cost probe)?
• Your current month's metered cloud usage (embed/rerank calls, tokens, remaining quota).

Local-first, verifiably. Everything on the page is collected from local files and local SQLite databases, read-only. The only network calls are the npm version lookup and the cloud-usage tile (GET /usage, authenticated with your key). The page itself is static HTML with inline CSS — no scripts, no external assets — so it renders offline from file://.

Open the dashboard

1. Ask your agent (recommended)

The context server exposes a dashboard MCP tool, so in Claude Code (or any MCP host) you can simply say:

Show me the prom.codes dashboard.

The agent calls the tool, gets a compact JSON summary plus the path of the rendered page, and tells you where it is. Ask it to open the dashboard and it passes open: true, which also launches your default browser:

Open the prom.codes dashboard in my browser.

The page is written to ~/.prometheus/status/dashboard.html and re-generated on every call — bookmark it and refresh after re-running.

2. From the command line

With the recommended global install, the context binary doubles as a CLI:

node "$(npm root -g)/@prom.codes/context-mcp/dist/bin.js" dashboard

Or without a global install (slower first run):

npx -y @prom.codes/context-mcp dashboard

The CLI resolves the workspace like the server does (PROMETHEUS_WORKSPACE_ROOT → CLAUDE_PROJECT_DIR → current directory), writes the page and opens your browser.

Set PROMETHEUS_API_KEY in the shell if you want the key probe and the cloud-usage tile filled; without it those tiles explain themselves and everything else still works. The CLI is strictly read-only — it never creates or modifies an index.

What each section means

Servers. One row per server (context / memory / saver): every running session (workspace, version, PID, uptime, last tool call), the globally installed version, the newest published version, and an update badge. Running sessions come from heartbeat files — each server writes ~/.prometheus/status/<server>-<pid>.json on boot, refreshes it every ~60 s and deletes it on shutdown; crashed leftovers are cleaned automatically when the dashboard reads the directory. A yellow dot means the heartbeat is stale (process alive but not refreshing).

Indexed workspaces. Every local index under ~/.prometheus (one SQLite DB per project), with its project path, index counts and embedding coverage — the share of code chunks that actually have a semantic vector. Coverage is the single most important health number: lexical and graph search always work, but semantic ranking only covers what is embedded. If a workspace shows low coverage, open it and run the reindex tool (incremental — it only embeds what's missing). DB size includes the WAL sidecar.

Memory. Total records, split by type (semantic / procedural / episodic / working) and scope, how many belong to the current project, and the most recent session captures.

Setup health. Whether the Claude Code awareness hooks are installed (and at which scope), and whether your PROMETHEUS_API_KEY passes the zero-cost validity probe (a free identity call — no credits spent).

Cloud usage. Current period's metered embed/rerank calls and tokens, your monthly call limit and what's remaining — fetched from GET /usage with your key. Deep links to app.prom.codes for keys and billing.

Status without the dashboard

Everything above is also available as structured data, straight from the MCP tools — useful when you want the agent to reason about state rather than show you a page:

• index_status (context) — workspace, index counts, embeddings.coverage { embeddedChunks, totalChunks, percent }, index.lastIndexedAt, hook state, key reachability, and an update block (see below). Call it whenever search feels off.
• memory_status (memory) — record counts, mirror state, key probe, plus the same update block for the memory package.
• status (saver) — installed rule blocks per runtime, key state, update block.
• list_workspaces, framework_overview — index roll-up and detected frameworks for the current workspace.

The update block in all three looks like this:

{
  "current": "0.10.0",
  "latest": "0.10.0",
  "updateAvailable": false,
  "command": "npm install -g @prom.codes/context-mcp @prom.codes/memory-mcp @prom.codes/saver --ignore-scripts=false --foreground-scripts"
}

It is cache-first (the version check hits npm at most once a day), and dev/workspace builds report updateAvailable: null instead of guessing.

Updating safely: update_servers

You learn about updates three ways: the update badge on the dashboard, the update block in any status tool, and — in Claude Code — a [prom.codes update] line that the SessionStart hook injects at the start of a session once a newer version is published.

To actually update, ask the agent to run update_servers (a context-server tool that updates all three packages). It never runs npm install while servers are running — a running server locks its native modules (especially on Windows), and an in-place install can abort halfway and corrupt the installation. Instead:

1. It reports the plan: installed vs latest versions, how the server is installed (global / npx / dev), whether your npm has ignore-scripts=true hardening, and every prom server currently running (from the heartbeats).
2. It launches a small detached updater process and tells you what to do: reload or close your editor windows. The updater waits until every prom server has exited, then runs the one documented upgrade command (always with --ignore-scripts=false --foreground-scripts, so hardened corporate npm setups don't end up with a broken native module).
3. Pass force: true (explicitly — never the default) if you can't close the other windows: the updater then terminates the remaining servers itself. This is safe — the index uses a crash-consistent WAL — but unsaved in-flight indexing in those sessions is simply cut off.
4. After your next reload, the outcome appears in index_status.update.lastResult (and as a boot log line).

dryRun: true shows the plan without starting anything. If you run the servers via npx …@latest, there is nothing to install — restarting the session already picks up the newest version. And the manual fallback always works: close all editor windows, then run the update command shown above.

The /usage endpoint

The cloud tile is backed by a free, key-authenticated endpoint you can also call yourself:

curl -H "authorization: Bearer $PROMETHEUS_API_KEY" https://api.prom.codes/usage

{
  "ok": true,
  "period": "2026-07",
  "embed": {
    "calls": 2465,
    "tokens": 35388627,
    "monthlyCallLimit": 1000000,
    "remainingCalls": 997535
  }
}

Reading your usage never costs credits. Rerank calls currently meter into the same counters as embeddings.

Files on disk (reference)

Set PROMETHEUS_STATUS_DIR to relocate the status directory (rarely needed; mostly for tests).