README.md

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 shared left rail presents AI, Tasks, and Productivity as the three top-level areas. AI expands to separate Metrics and Orchestrator leaves; that grouping changes wayfinding only and does not merge their Docker and Windows-local runtimes. -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. The daily workbench has a separate Productivity contract. 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
AI · Metrics	Shows exact-account Claude/Codex plan and activity readings plus the existing Azure and owner-configured cards, layout, filters, and trends from the Docker Dashboard runtime.
AI · Orchestrator	Presents the fixed four-identity × two-provider matrix, exact session state, capacity, attention, compatibility, and controls from the separate Windows-local runtime.
Cacheboard Tasks	Provides a desktop-first six-column workspace with bounded per-column scrolling, workflow jumps, global and inline capture, actionable Focus, search/filters, progressive project editing, guarded unsaved detail edits, reversible Archive/Trash, and quick actions that retain the existing orchestration authority gates.
Cacheboard Productivity	Turns the canonical Focus projection into a daily queue with a document-memory focus/break timer, honest session pulse, bounded multi-task Brain Dump, and deterministic Get unstuck guidance. It adds no task store, scheduler, provider authority, or durable time record.
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 and per-column capture into one universal board; a bounded desktop workbench with workflow jumps and internal column scrolling; actionable Focus rows; compact search/filters; pointer/touch, menu, and keyboard movement; progressive project editing; an explicit unsaved-change close gate; conflict-preserving detail/activity; and reversible Archive/Trash with no P0 permanent purge. Quick actions such as Plan next, Start work, Mark blocked, Send to review, Complete, Duplicate, and Run with AI… retain canonical movement, confirmation, scheduler, and automation-admission boundaries; task text, projects, and links never grant authority.

The current Productivity source at /productivity reuses the server-derived Focus queue and ordinary Work Item capture endpoints. Its countdown, completed-block observations, rescue choice, and Brain Dump draft/retry state are held only in the loaded browser document. Reloading clears those observations; successfully submitted Brain Dump lines persist only because they become ordinary idempotent Inbox Work Items. The workspace makes no live-provider, durable-time, or productivity-score claim. Current and historical fixture/local/live evidence remains separate 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, Tasks at /tasks, and the nonauthoritative Productivity workbench at /productivity
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. Standalone setup opens its transactional guided browser login when that local refresh state is unusable (for example missing, expired, invalid, or incomplete) or -ForceLogin is explicit. During one-click startup, the launcher attempts silent exact-account repair first. It invokes the same account's -ForceLogin transaction after an explicit browser-required result, a strictly typed byte-unchanged pre-rotation failure, or a restarted Dashboard readiness rejection of that account's silent result. Guided authentication is capped at one attempt per exact account. Unknown, identity, path, ACL, mapping, or credential-custody failures stop instead of guessing. 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 remain explicit and do not trigger an automatic Codex login; Claude recovery follows the stricter bounded all-four convergence below. If Docker remains unavailable, the launcher reports bounded context/process/Desktop diagnostics and leaves settings unchanged. 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 or is not ready, the launcher first uses setup's credential-only -RefreshOnly -SkipRestart -NonInteractiveRecovery mode after requiring the existing exact .env mapping and identity metadata. It repairs a damaged access token from a still-usable saved refresh credential, retries bounded pre-rotation native failures with fresh isolated stages, and rereads a concurrently rotated exact profile before another exchange. Promotion requires first-party status and the configured exact email. A locally unusable refresh credential returns an explicit browser-required result. That result, or a strictly typed pre-rotation failure that persists while the live credential remains byte-for-byte unchanged, makes the ordinary launcher open the same account's existing transactional guided login with -ForceLogin. An ambiguous provider outcome without that strict typed proof remains an unknown failure and stops. The guided candidate stays isolated until first-party status proves the configured exact email, then promotion is atomic.

Silent CLI success alone is not the convergence boundary. The launcher restarts the Dashboard and rereads authenticated readiness. If that restarted Dashboard rejects an account that was repaired silently, the launcher gives that exact account its one transactional guided attempt and restarts the Dashboard again. An account that already consumed its guided attempt is never placed in a login loop. Normal startup claims ready only when the restarted Dashboard reports all four Claude plan profiles ready, identity verified, non-mismatched, and mapped to their configured exact emails. A cancelled or failed guided login, wrong identity, mapping drift, unsafe path or ACL, unknown failure type, written-stage custody, uncertain post-rotation state, or failed final all-four check remains a hard stop. -SkipClaudeRecovery is the explicit diagnostic opt-out when the owner intentionally accepts unrepaired Claude plan rows; that exception is not an all-four Claude-readiness claim. 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 Cacheboard with its signed 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.
• Productivity timer/session observations and unsent Brain Dump text stay in the current document only. They are not a durable worklog, browser-storage task cache, provider prompt, or alternate task authority; only successful ordinary Work Item creates persist.
• 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.