Cacheboard

Cacheboard is a local-first personal operations dashboard and Claude/Codex control plane. It still shows changing usage, reset windows, and other personal metrics in one place, but it can also inventory, launch, queue, coordinate, and supervise the provider chats that its exact-profile adapters can safely address.

Normal one-click startup now enters the authenticated Orchestrator Command Center first. The original Metrics Dashboard remains available behind the visible reciprocal Dashboard link; -NoOrchestrator intentionally retains the dashboard-first metrics-only startup path.

The current setup is four stable identity slots—earl, bbpyderz, ehayestrainer, and claude—with one isolated Claude login and one isolated Codex login per slot. The claude slot is verified as claude@bigbwain.com on both providers. The verified Claude and Codex email must match inside a shared slot; friendly labels and subscription tiers are display-only metadata. The dashboard also supports cloud, home-lab, finance, social, health, and security cards. Fitbit durable refresh is intentionally one verified Fitbit identity per local backend; a second identity is rejected rather than silently sharing the wrong profile.

Documentation

Start with the documentation index for the canonical reading path, current-state snapshot for implemented surfaces and open gates, architecture map for runtime/source ownership, and development guide for exact local gates. Agents and concurrent contributors must also follow AGENTS.md. Dated plans, handoffs, and verification receipts are historical unless a fresh current-tree check says otherwise.

High-level feature overview

Surface	What it does now
Metrics Dashboard	Shows exact-account Claude/Codex plan and activity readings plus the existing Azure and owner-configured cards, layout, filters, and trends.
Cacheboard Orchestrator	Presents the fixed four-identity × two-provider matrix, exact session state, capacity, attention, compatibility, and controls from one responsive UI.
Cacheboard Tasks	Provides a compact board-first six-column workspace with global capture, Focus, collapsed Now/Risk guidance, search/filters, projects, bounded saved views, conflict-preserving detail/activity, reversible Archive/Trash, and quick actions that retain the existing orchestration authority gates.
Multi-chat sessions	Keeps many durable chats under each lane, targets actions by exact session, and uses a bounded encrypted dispatch queue when immediate provider capacity is unavailable.
Existing chats	Discovers bounded Claude Code sessions and Codex threads for exact local profiles, observes active external owners, and adopts only an exact quiescent conversation through a supported resume/handoff path.
Collaboration	Coordinates Project Rooms, isolated Git worktrees/branches, path leases, explicit context delivery, deterministic automations, and a provider-neutral Attention Inbox.
Remote hosts	Enrolls outbound per-user agents on Windows, Linux, and macOS; lists exact-profile provider sessions; and centrally controls Cacheboard-owned read-only remote chats with launch, message, interrupt, stop, resume/reconcile, and exact-question answers.
Phone controller	Pairs an iPhone/iPad or other tailnet browser with a five-minute single-use code and presents the same capability-gated responsive controller; execution stays on an enrolled computer.
Typed connectors	Models pinned SSH observation, cloud-agent targets, and immutable container/pod observation requests, and runs wmux-owned terminal inventory/control without exposing a general shell or Docker socket. The host-agent package includes the fixed SSH observation entrypoint; each SSH account still needs its exact wrapper/PATH proof and pinned target configuration. Container work needs an enrolled host to advertise the matching adapter.
Tools & Memory	Visually assigns supported Claude skills/plugins or Codex skills to one exact managed chat and shares curated context-only summaries, decisions, facts, and handoffs between selected Claude/Codex chats.
Compatibility catalog	Classifies every known installed-provider method as direct, native-only, observed, handoff, unavailable, or prohibited instead of hiding adapter gaps.

The honest limit is important: Cacheboard does not seize an actively owned Terminal, Desktop, IDE, Claude.ai, ChatGPT, or other consumer web chat. Logical chats are not capped at eight, but actual simultaneous inference remains bounded by the machine, configured scheduler, subscription, provider concurrency, and rate limits. Remote managed chats are currently read-only and never expose provider approval or workspace-write controls. See the universal control-plane map for the exact implemented boundaries.

Current status

The multi-account Dashboard and universal-controller implementation are present in the current working tree:

The current Tasks source provides global Capture task into one universal board; compact toolbar search/filters; Focus and a collapsible Now/Risk rail; pointer/touch, menu, and keyboard movement; conflict-preserving detail/activity; and reversible Archive/Trash with no P0 permanent purge. Quick actions such as Work now, Block, Review, Done, Duplicate, and Automate keep confirmation and existing scheduler/automation admission boundaries; task text, projects, and links never grant authority. Current and historical fixture/local/live evidence is recorded separately in the verification ledger.

Registry invariant: four shared identity IDs × two providers = eight verified provider identities. Each shared identity contributes four exact-source readings, for 16 internal readings total. The dashboard presents those readings through one user-owned Claude overview card and one user-owned Codex overview card by default.

• Claude plan limits: account-scoped OAuth credentials and Anthropic's undocumented subscription-usage endpoint.
• Claude activity: account-scoped Claude Code JSONL transcripts with today, week, month, and all-time totals.
• Codex plan limits: the Windows Orchestrator reads the official Codex app-server rate-limit response and publishes it through the signed metrics snapshot.
• Codex activity: the Windows Orchestrator reads the official Codex app-server usage response, normalizes today/week/month/all-time token totals, and publishes the same signed snapshot generation.
• Strict account identity: expected email plus live or recorded provider identity must agree, and a shared ID cannot map to different emails across providers.
• Unified dashboard grid: one Claude overview and one Codex overview sit beside Azure and other custom cards. Each provider overview can show every verified account reading or only the exact account/metric rows the owner selects. Capacity bars use provider percentages; activity bars are explicitly relative comparisons, never invented provider limits.
• Editable layout: the persisted 2/3/4-column switch starts at four columns on a wide desktop and uses responsive phone/tablet fallbacks. Arrange mode persists mixed managed/custom order; it resets the active filter to All so no hidden neighbor is moved accidentally.
• Owner-controlled cards: every visible card can be edited, reordered, hidden, removed, and deleted. Removing a Claude or Codex overview is durable across reloads and startup; Cacheboard restores a missing provider template only after the owner explicitly chooses Add provider cards. Exact verified identities remain locked only inside the invisible source readings so one account can never be relabelled as another. Example cards are opt-in and hidden by default.
• Azure Monitor resource metrics: discover the real platform-metric catalog for a full Resource ID, then show one unambiguous raw Average/Total/Minimum/Maximum/Count over a chosen lookback. Optional alert thresholds are user-set and never presented as Azure quotas.

The owner's eight intended provider profiles were enrolled and live-verified by 2026-08-10: all four Claude identities and all four Codex identities matched their expected emails, authenticated /health reported every account ready, and each plan/activity route returned successfully. This is a local verification receipt, not a guarantee that future provider responses, reset behavior, or credential refreshes will remain unchanged.

How the pieces fit

Layer	Responsibility
index.html	Single-file UI, card configuration, account selection, trends, refresh controls
server/server.mjs	Authenticated local API, Claude collection, read-only verified Codex snapshot projection, proxy/OAuth helpers
Claude profiles	One CLAUDE_CONFIG_DIR per subscription, containing credentials, projects, and verified metadata
Codex Windows profile homes	%USERPROFILE%\codex-profiles\<id> under CODEX_PROFILES_HOST_DIR; the Orchestrator is the only active runtime that may verify, refresh, or replace these credentials
Codex signed metrics bridge	Protected codex-metrics.v1.json, atomically published by Orchestrator and mounted read-only at /bridge/codex for Dashboard verification and projection
Dormant Docker Codex volume	The historical cacheboard-codex-profiles volume remains declared and unmounted for an explicit owner-reviewed rollback; it is not active authority
server/.env	Stable account registry, exact expected emails, display labels, secrets, and paths
orchestrator/	Loopback Hub, SQLite workflow state, provider adapters, queue, rooms, automations, host fabric, connectors, Tools & Memory, and responsive controller
Host Agent	Outbound per-user Windows/Linux/macOS process for signed inventory and read-only managed provider control on an enrolled computer

The server is required for automatic subscription usage. Opening index.html directly still supports manual and browser-callable cards, but cannot safely aggregate local credentials or verify the Orchestrator's signed Codex snapshot.

Quick start on Windows

Prerequisites: Docker Desktop, Claude Code on PATH, and Node/npm on PATH for the pinned Codex setup fallback.

From the repository root:

Copy-Item server/.env.example server/.env

# Exact emails make each sign-in an enforced identity assertion.
$earlEmail = Read-Host 'Exact email for earl'
$bbpyderzEmail = Read-Host 'Exact email for bbpyderz'
$trainerEmail = Read-Host 'Exact email for ehayestrainer'
$claudeEmail = Read-Host 'Exact email for claude'

.\server\setup-claude-profiles.ps1 -Accounts `
  "earl=$earlEmail", `
  "bbpyderz=$bbpyderzEmail", `
  "ehayestrainer=$trainerEmail", `
  "claude=$claudeEmail" `
  -SkipRestart

.\server\setup-codex-profiles.ps1 -Accounts `
  "earl=$earlEmail", `
  "bbpyderz=$bbpyderzEmail", `
  "ehayestrainer=$trainerEmail", `
  "claude=$claudeEmail"

Each script verifies the provider's exact signed-in email, writes only non-secret identity metadata, and updates server/.env when mappings change. Claude setup first uses a locally saved, usable refresh credential with a signed Claude Code 2.1.233+ executable and then verifies the exact email; it opens a browser only when that local refresh state is unusable (for example missing, expired, invalid, or incomplete) or -ForceLogin is explicit. An ambiguous provider failure stops with retry/manual guidance and never silently falls back to browser login. Codex setup accepts only a subset of the fixed four IDs and requires port 8790 to be proven closed before it resolves Codex or changes a profile. Run it in a deliberate stopped-Orchestrator window, normally before starting Cacheboard after sign-in; never stop an unknown listener by PID. Neither script assumes a label is an identity. If the value after = is an email address, it is enforced as the expected identity and setup aborts on a different login; otherwise it is only a label. Setup also aborts if the same stable ID maps to different verified emails across Claude and Codex.

Windows Orchestrator is the sole active Codex credential writer. It uses each authoritative Windows profile to perform saved-credential refresh, verifies the exact configured email, and atomically publishes one authenticated HMAC-signed metrics snapshot. The Dashboard has no Codex executable, credential mount, refresh path, or fallback writer; it reads only the protected read-only bridge. Ordinary startup does not open a Codex browser. It prints an exact-account setup command only for typed credential_expired, credential_unavailable, or refresh_rejected states; identity mismatch, temporary ambiguity, or Orchestrator absence never guesses that login is the repair.

Set a long random DASHBOARD_TOKEN in server/.env, then start the service:

docker compose -f server/docker-compose.yml up -d --build

That raw Compose command is a degraded Dashboard diagnostic, not the normal complete-product start. It does not prepare or validate the protected host bridge; without the launcher-provided bridge, all four Codex rows remain orchestrator_unavailable. Use Start-Cacheboard.cmd for the supported integrated flow.

After the first setup, double-click Start-Cacheboard.cmd for one-click startup. It prepares and ACL-verifies the protected Codex metrics bridge before every Compose call, starts Docker Desktop through the supported Desktop CLI (with an installed-executable fallback), verifies Dashboard health and current UI, then reuses, gracefully refreshes, or starts the exact Windows Orchestrator. The broker refreshes saved Codex credentials as required, verifies exact emails, and publishes exactly four ordered signed records before the launcher continues to provider readiness. Typed unavailable Codex rows are reported without blocking every other lane or automatically opening login. If Docker remains unavailable, the launcher reports bounded context/process/Desktop diagnostics and leaves settings unchanged. Normal one-click startup does not silently degrade; the explicit Start-Cacheboard.cmd -OrchestratorOnlyIfDockerUnavailable mode starts the local broker through a direct one-time loopback browser ticket and clearly marks the Dashboard and its usage cards unavailable. -NoOrchestrator instead uses a distinct protected empty bridge and requires all four Codex rows to be orchestrator_unavailable, so it cannot expose a prior signed snapshot.

If a Claude plan credential has expired, the launcher uses setup's credential-only -RefreshOnly mode, which first requires the existing exact .env mapping and identity metadata. It then attempts the saved refresh credential through signed Claude Code 2.1.233+ in an isolated profile and accepts it only after exact-email, first-party status verification. A locally unusable refresh state (for example missing, expired, invalid, or incomplete) uses the guided browser flow; an ambiguous provider failure stops with retry and explicit -ForceLogin guidance instead of silently opening a browser. Recovery remains one exact configured email at a time; unrelated ordinary sibling directories in the configured Claude root are ignored as identities, while links and unsafe configured identity paths still fail closed. A wrong identity is rejected without replacing the live credential. Ordinary setup remains the enrollment path and writes missing metadata or .env mappings even when the saved credential is already ready. The launcher then creates a short-lived browser ticket and opens a cache-busted dashboard with a signed HttpOnly local session.

If that launcher finds an older Orchestrator from this installation, its default behavior is a bounded graceful refresh—not a forced process replacement. It proceeds only when the broker is authenticated as the exact owner, advertises /healthz.lifecycle.contract as cacheboard-orchestrator-lifecycle-v1, still matches the observed running artifact, and reports no active work. -NoRuntimeRefresh opts out. A busy, unowned, legacy, or opted-out stale broker is left untouched and startup prints a concise actionable error rather than raw structured receipt data. The launcher never uses Stop-Process, taskkill, or another force-kill fallback, and it does not start the current broker until the old PID, loopback listener, and owner lock have all closed. See Runtime artifact identity and restart boundary.

The page discovers the eight verified provider logins and maintains 16 exact Claude/Codex capacity and activity readings behind two provider overview cards. The Claude overview, Codex overview, Azure, and other custom cards share the same column density and saved order. Provider cards are ordinary owner-controlled cards: deleting one is durable, and restoring one requires the explicit Add provider cards action. Examples appear only after explicit opt-in. The visible Orchestrator link uses the authenticated Dashboard session and a server-side bridge to mint a one-time loopback ticket; provider credentials and DASHBOARD_TOKEN never enter cards, page JavaScript, HTML, logs, or URLs. Orchestrator then keeps its own signed exact-origin session in sessionStorage and uses separate single-use SSE tickets, rather than widening the Dashboard cookie. The owner workstation also has a Start Cacheboard.cmd wrapper on the Desktop.

The launcher opens http://127.0.0.1:8787 with the secure local session already established. Verified Claude and Codex cards are discovered and provisioned automatically; Settings remains available for a different remote backend or additional metric cards.

Current Orchestrator completion evidence is maintained in the verification ledger. The 2026-08-12 receipts remain historical evidence for the all-eight read-only, two-provider control, Project Room, automation recovery, online backup, owner-only ACL, and desktop/mobile browser gates. The implementation has expanded materially since those receipts; use the ledger's current-tree section for the final provider-free count and the still-open live Windows-to-Linux/macOS gate. No machine reboot was performed in the dated 2026-08-12 evidence; its restart receipt covers the broker process.

Verify identity before trusting a number:

$headers = @{ Authorization = 'Bearer YOUR_DASHBOARD_TOKEN' }
Invoke-RestMethod http://127.0.0.1:8787/health -Headers $headers

Every intended entry in claudeAccountDetails and codexAccountDetails should have ready: true, identityVerified: true, and mismatch: false.

Claude identity evidence is captured by the setup script, not re-read from a public runtime identity API on every usage request. If a Claude profile is ever signed out, switched, or reauthenticated outside the setup script, rerun server/setup-claude-profiles.ps1 before trusting its cards. Codex identity is checked by the Windows Orchestrator through the pinned app-server before the matching signed snapshot record is published; the Dashboard never performs that provider read.

Azure Monitor setup (browser-only, no client secret)

Cacheboard uses Microsoft's delegated SPA flow, so these steps deploy no Azure compute, storage, database, or monitoring workspace. Start by reading platform metrics from an existing resource; Azure Monitor API pricing can change, so check the current pricing page before adding many cards or frequent external polling.

1. In Microsoft Entra app registrations, create a single-tenant app: Accounts in this organizational directory only. Do not create a client secret.
2. Register the SPA redirect URI exactly as http://127.0.0.1:8787/. The portal form rejects an HTTP IP-literal redirect, so open the app's Manifest and add it under spa.redirectUris as documented for loopback redirect URIs. Leave implicit access-token and ID-token issuance disabled.
3. Under API permissions, add Azure Service Management -> Delegated permissions -> user_impersonation. Cacheboard requests only the corresponding https://management.azure.com/user_impersonation scope. This is an authorization-code flow with PKCE for a SPA, not an app secret or service-principal login.
4. Copy the Directory (tenant) ID and Application (client) ID from the app overview. Do not use the application's Object ID.

Delegated calls inherit the signed-in user's Azure RBAC. If that user can already read the resource and its metrics, add no role assignment. Only after a real 403 should you grant that user Monitoring Reader at the narrowest useful resource or resource-group scope.

To create the first card, choose Add card -> Azure -> Azure Monitor resource metric, enter the tenant ID, client ID, and the existing resource's full Resource ID, then click Connect Microsoft Account. After sign-in, click Discover, choose one supported metric and aggregation, keep Observe mode unless you have a meaningful alert threshold, then Save and Refresh. Cacheboard persists the stable Microsoft account binding with that card so it cannot silently refresh through another cached identity.

Live setup receipt (2026-08-10): the owner's single-tenant registration discovered 37 platform metrics for an existing production App Service, and a persisted Requests / Total / Last hour card refreshed successfully through the exact bound Microsoft identity, ehayestrainer@gmail.com. That is the only Azure identity in scope; the other registered emails are Claude/Codex identities only. No client secret, new Azure resource, or additional RBAC role was needed. Cost, quota, and resource-health cards still require separate owner-specific live verification.

Metric semantics

• Plan-limit cards show provider-defined rate-limit windows as percentages and reset times.
• Activity cards show observed token consumption. They do not infer a provider token ceiling. Any target shown for activity is the user's own planning target.
• Claude and Codex overview cards can switch between Bars and Values or share the dashboard's 2/3/4-column density without changing their selected source rows. Activity bars compare the displayed periods only; they are not historical trends or quota gauges.
• Azure Monitor metric cards use the official FULL interval for the selected lookback and preserve Azure's returned unit. Observe mode assigns no invented good/bad meaning; High/Low modes compare only with the card's explicit user threshold. Multi-dimensional responses require a filter or rollup instead of silently choosing one series.
• Claude transcript activity covers Claude Code only; it does not include claude.ai web/mobile messages.
• OpenAI API-key billing and Codex/ChatGPT subscription usage are different data sources and remain separate cards.
• Claude's subscription quota endpoint is undocumented and may change. Failures are surfaced; Cacheboard does not substitute a fabricated value.

Security defaults

• Compose publishes only to 127.0.0.1 unless CACHEBOARD_BIND is deliberately changed. A host/port change must also be reflected in ALLOWED_ORIGINS.
• Every API route except /healthz requires the bearer token.
• Exact expected emails prevent a valid credential for the wrong account from being silently displayed.
• Credentials stay in gitignored provider profile directories and provider-specific local custody; secrets and tokens are never returned to the browser.
• The local dispatch queue encrypts pending provider prompts/action payloads at rest. Remote Host Fabric command history does not: bounded remote managed launch/follow-up prompts and non-secret question answers are plaintext command payloads in broker SQLite and its backups until an explicit future retention feature removes them. The prompt is not duplicated into session-title metadata; an optional operator-entered chat title of at most 200 characters is stored separately in the session row. Keep secrets and unrestricted transcripts out of remote prompts and answers, and sensitive text out of titles.
• Windows setup and startup protect server/.env plus managed Claude/Codex credential roots and files with inheritance removed and FullControl limited to the current user, SYSTEM, and BUILTIN\Administrators; reparse points and path escapes fail closed.
• Claude profiles and the normalized Codex metrics bridge are mounted read-only. The Dashboard image contains no Codex runtime or credential path.
• The historical Docker Codex volume remains sensitive dormant custody. It is unmounted and is never an automatic fallback or reactivation path while the Windows writer exists.
• Do not run docker compose -f server/docker-compose.yml down -v as routine cleanup. It would delete both active Dashboard state and the dormant rollback volume. Any future rollback requires an owner-reviewed authority transfer after the Windows writer is deliberately stopped.

See server/README.md for the metrics environment and route contract, orchestrator/README.md for controller operation, Host Agent installation for Windows/Linux/macOS enrollment, NOTES-multi-account.md for identity/reauth operations, and the verification ledger for current versus historical evidence.

Cacheboard-Setup-and-Tasks.md is the source for the setup handout. Use the pinned CPython 3.12 procedure in tools/README.md, regenerate the checked-in PDF, and visually inspect every page before treating the PDF as current.