Doctor checks

Doctor lives at Settings ▸ Doctor. It runs the full readiness catalog against your install — one row per check, in the groups below — and this page is the per-check reference. The tables are generated from the same check catalog the app executes: the Guidance column is the exact hint a non-passing row shows in the app, and Fix action is the one-click button the row offers, when it has one.

Doctor itself is never gated. It stays open when you are signed out and when a subscription has lapsed, because that is precisely the state it exists to help you diagnose.

If you are starting from a symptom rather than a check, use Troubleshooting instead — it maps the same catalog onto the problems you actually see, in order of likelihood.

How to read a row

• Pass — the real condition was verified: a binary answered on PATH, a service answered its health endpoint, a file exists where expected.
• Fail — a prerequisite is genuinely missing and needs your action. Fail is reserved for four things: a binary that is not on PATH, a missing environment file, a runtime environment that was never created or whose interpreter is broken, and a missing or partial platform tree. Nothing else in the catalog can fail.
• Info — a degraded, skipped, or not-yet state with a precise cause: a service that is not running, a component you chose to skip, an engine you have not installed, a key you have not set, a control plane you switched off, or a check that cannot run because the service it needs is offline. "Not started yet" is never treated as broken — an install with several info rows can be perfectly healthy.

The Can report column lists which of these states each check can produce — a check that can never report fail cannot block you. Fix actions delegate to the exact same operations the Dashboard's Platform Health card uses; there is no separate Doctor-only mutation path. A few rows also carry a small choice control rather than a button, where the useful action is a preference rather than a repair.

Components

The first group is not a health check at all — it is the standing control over what Command Center sets up for you. The same choices appear as checkboxes in the first-run wizard, and this group is their always-available twin, so anything you skipped during setup is one click from being added later. Both surfaces write the same setting, so they can never disagree.

Everything here is on unless you turn it off. An enabled component passes; a skipped one is an info row stating what stops working, never a failure — skipping is a legitimate choice about your own machine, not a broken install. Two of the components are load-bearing (the managed Python runtime and the knowledge graph); their rows say so rather than silently letting you switch off the platform's own foundation.

Two properties are worth knowing before you use Skip:

• Skipping never removes anything already installed. It stops future automatic provisioning, and nothing else. Removal stays an explicit action on the component's own row further down the board.
• Skipping is not a lock. An explicit install — pressing Provision, Install, or Fetch now on any row below — always proceeds, because asking for the install is itself the act of enabling it.

The rows in this group answer should this be here. The rows in every group below answer is it here, and is it working.

Check	Can report	Fix action	Guidance
Managed Python runtime	pass · info	Skip · Enable	—
Knowledge graph	pass · info	Skip · Enable	—
Media tools (ffmpeg)	pass · info	Skip · Enable	—
Video engine runtime (Node)	pass · info	Skip · Enable	—
Speech-to-text (Whisper)	pass · info	Skip · Enable	—

Core

Core covers the prerequisites Command Center cannot provide for itself, plus the configuration spine that points everything at everything else.

1. Binaries — Node.js and npm for the app and the video engines, the agent CLI that runs your agents, an optional second agent CLI, and, on Windows, which terminal console the app is driving. A binary that is not on PATH reports fail with the vendor to install it from; the agent CLI is the one prerequisite Command Center cannot provision for you. One wrinkle worth knowing: the optional second-CLI row reports fail when absent even though nothing depends on it, so an install that uses a single agent CLI is perfectly healthy with that row red.
2. Configuration — the environment file exists, the two optional Gemini key slots are present and loaded by the running services, and the agent tooling manifest (.mcp.json) has been generated. Key rows deep-link to Settings ▸ API Keys; see the configuration reference for what each key unlocks. A key saved while a service is running is invisible to it until that service restarts — the rows detect and name this state.
3. Folder trust — agent CLIs trust folders individually. The row's single action trusts your install root for every installed engine at once, so a second engine can never be the one nobody remembered to trust.
4. Platform integrity — the platform tree is present and complete at your install root, shipped doctrine (agents, skills, protocols) can be refreshed after an update without overwriting your edits, stray legacy config is flagged, and the fleet-wake and session-resume hooks are installed.
5. Agent tooling freshness — whether the MCP server code on disk is newer than the processes currently serving it. MCP servers are started by your agent CLI, not by Command Center, so the remedy is to restart the agent CLI; restarting Command Center does not affect them.

Python is deliberately not a Core binary. It moved to the Runtime group as a bootstrap note, because a green Python row was a misleading signal: the platform's services do not run on your system interpreter.

Check	Can report	Fix action	Guidance
Node.js	pass · fail · info	—	install Node.js >= 22 from nodejs.org — needed for the app UI + video engines
npm	pass · fail · info	—	ships with Node.js — reinstall Node if missing
Agent CLI (claude)	pass · fail · info	—	install Claude Code (claude.ai/code) — needed to use the MCP servers
Agent CLI (codex, optional)	pass · fail · info	—	optional second engine — install Codex (chatgpt.com/codex) to run Codex terminals alongside Claude
Terminal console (ConPTY)	pass · info	—	Codex terminals will have no scrollback on Windows 10. Reinstall Command Center to restore the bundled console; nothing else is affected.
.env configured	pass · fail	—	Settings ▸ API Keys writes this file automatically the first time you save a key
Gemini key (KB · memory · embeddings)	pass · info	Open API Keys	set GEMINI_API_KEY in Settings ▸ API Keys (free tier); keyword memory search and graph queries keep working without it
Gemini image key (imagegen)	pass · info	Open API Keys	set GEMINI_IMAGE_API_KEY in Settings ▸ API Keys (paid tier, imagegen only), then restart the imagegen daemon so it picks the key up
.mcp.json (agent config)	pass · info	Generate	writes .mcp.json from .env + the template with real absolute paths
Codex profile (MCP + grounding)	pass · fail · info	Regenerate	the Codex profile probes need one Command Center restart to activate
Folder trust (agent CLIs)	info	Trust this folder	if this is a brand-new folder, trust it once so your agent CLI skips its own trust prompt
Platform tree present	pass · fail	Re-run lay-down here · Re-run lay-down	every daemon/MCP path below is resolving against nothing here — re-run the onboarding wizard's home-folder step, or point Settings ▸ project root at the folder Command Center actually laid the platform down into
Doctrine (agents · skills · protocols)	pass · info	Refresh doctrine	updates add new agents/skills/protocols but never overwrite one you changed — use this only to restore the shipped versions (your copies are backed up first)
Config layout	pass · info	Remove stray file	left by an early install — the shell reads app/.env; this file is unused and safe to remove
Fleet wake & session-resume hooks	pass · info	—	terminal session-resume and the fleet idle-nudge silently no-op without these — run `python .claude/hooks/cc_install_hooks.py` from the install root (writes machine-correct paths; new pane sessions pick them up)
MCP servers · code freshness	pass · info	—	Stop the Shared Agent Memory daemon (Dashboard ▸ Platform Health) and a Claude Code session takes the port back within ~25s, at which point this check resumes on its own. Either way: MCP servers are started by Claude Code, so restart Claude Code to load current MCP code — restarting Command Center does not affect them.

Runtime

Runtime is where the platform's Python side is installed, updated, and repaired — and it is a working surface, not just a report. Four kinds of row live here:

• Bootstrap Python — any Python 3.8 or newer, used only to launch the provisioner. It is an info row when present, because it is not what the services run on. It fails only when there is no Python at all, which is the one state that genuinely blocks: nothing can bootstrap the provisioner.
• uv — the package manager that does the real work. The provisioner installs a pinned, checksum-verified copy automatically.
• The per-service environments — one row per background service. Each row reports what that environment's own interpreter answered, not merely whether a folder exists, so a present-but-broken environment is distinguishable from a missing one: the first offers Repair (recreate from scratch), the second offers Provision.
• The runtime provisioner — the summary row, and the one-pass install. Provision installs uv, a pinned Python, and every missing environment together; expect a few minutes on first run. Once healthy, the row keeps a Re-provision action for picking up refreshed dependencies, and shows the runtime version stamp it was built at.

One info state is worth recognizing: "platform updated since last provision". An app update refreshes the platform tree but never touches your Python environments, so the row tells you the two have drifted and offers Re-provision. That is maintenance, not breakage.

Use these buttons rather than the terminal. The command-line provisioner still ships and is documented at the bottom of this page, but it exists for the case where the app will not start.

Check	Can report	Fix action	Guidance
shared-agent-memory venv	pass · fail	Repair · Provision	—
knowledge-base venv (arcadedb + gemini-direct)	pass · fail	Repair · Provision	—
observer venv	pass · fail	Repair · Provision	—
email-server venv	pass · fail	Repair · Provision	—
routines daemon venv	pass · fail	Repair · Provision	—
imagegen-daemon venv	pass · fail	Repair · Provision	—
Bootstrap Python	fail · info	—	the tool-detection command needs one restart to activate — re-check after the next Command Center restart
uv (Python package manager)	pass · fail · info	Provision	the provisioner installs a pinned, sha-verified uv automatically — Provision below
Runtime provisioner	pass · fail · info	Provision · Re-provision	`scripts/provision_runtime.py` ships only in an installed build — the dev monorepo uses existing per-server venvs

Daemons

One row per background service, plus the graph database. A stopped daemon is an info row, not a failure — the fix action starts it directly, and autostart (Dashboard ▸ Platform Health) is on by default, so the usual cause of an all-stopped board is that autostart was deliberately turned off.

Two rows behave differently from the rest:

• Shared Memory reports its entry count as well as its liveness, because a service that is listening but empty is not the same as a working memory store. It is app-managed with a Start button like the others. It also has a second possible host: an agent session can serve the same surface as a hot spare, which is why the row names which host is answering and why the service can come back on its own after you stop it. Command Center can only stop a host it owns.
• ArcadeDB offers to provision a local, no-container instance the first time (a few minutes), after which it gets a plain Start like the rest. In docker/remote mode the row is status-only, because the server's lifecycle is not Command Center's to manage.

Check	Can report	Fix action	Guidance
Observer	pass · info	Start	starts on launch when autostart is enabled (Dashboard ▸ Platform Health)
Routines	pass · info	Start	starts on launch when autostart is enabled (Dashboard ▸ Platform Health)
Imagegen	pass · info	Start	starts on launch when autostart is enabled (Dashboard ▸ Platform Health)
Voice	pass · info	Start	starts on launch when autostart is enabled (Dashboard ▸ Platform Health)
Knowledge Base	pass · info	Start	starts on launch when autostart is enabled (Dashboard ▸ Platform Health)
MCP Gateway	pass · info	Start	starts on launch when autostart is enabled (Dashboard ▸ Platform Health)
Email	pass · info	Start	starts on launch when autostart is enabled (Dashboard ▸ Platform Health)
Shared Memory	pass · info	Start	starts on launch when autostart is enabled (Dashboard ▸ Platform Health). A Claude Code session also hosts this surface as a hot spare, so it can come back on its own.
ArcadeDB	pass · info	Provision · Start	check the external ArcadeDB box, or switch to provisioned-local in Settings ▸ Database

Engines

The two video engines are opt-in installs — a fresh install shows both as info rows, which is normal until you decide you want video. The fix action opens the Video tab, where the per-engine install (and its license gate) lives. Once installed, the row also verifies the render browser the engine needs; that fetches automatically on first render.

Check	Can report	Fix action	Guidance
Remotion	pass · info	Open Video tab	opt-in per-engine install — the license gate lives in its own tab, not here
Hyperframes	pass · info	Open Video tab	opt-in per-engine install — the license gate lives in its own tab, not here

Media

Media tooling largely manages itself: ffmpeg/ffprobe fetches automatically the first time footage preparation or a video engine needs it, a pinned Node for the video engines installs on request into Command Center's own tools folder (no system change), and the Whisper speech-to-text models install once from Settings and serve both footage transcription and Voice's local speech-to-text.

Every row in this group carries a Prefer control — Auto, System, or Managed. It decides which install wins when you have both a managed copy and one on your PATH: Auto uses your system copy once its major version meets the pinned version, and falls back to the managed copy whenever the system version cannot be read. It only ever chooses between installs that both exist; it never causes one to be fetched. When your preference names an install you do not have, the row's detail says so rather than silently using the other one.

These rows need the routines daemon up to report live state; while it is down they show an info row saying exactly that.

Check	Can report	Fix action	Guidance
ffmpeg / ffprobe	pass · info	Fetch now	will auto-fetch on first use once the daemon is running
Node.js (video engines)	pass · info	Install Node	start the routines daemon to install or manage a bundled Node
Whisper models	pass · info	Open Speech-to-Text settings	shared by footage-prep transcription and Voice's local STT — installing once serves both

Account

One row: sign-in and subscription state. Not signed in is the shell baseline, shown as info — sign in from Settings ▸ Account to unlock Pro or Ultra features. When you are signed in and verified, the row shows your tier and nothing else, because the timings belong on the Account card where you would look for them.

When verification is not current, the row reads degraded (<reason>) — treated as unsubscribed, and the reason is the useful part. Your machine works for up to 72 hours from its last successful check; verification renews automatically at the halfway point, so an install that loses contact keeps working somewhere between 36 and 72 hours depending on when it dropped. There is no additional grace period after that — the tolerance is that window and nothing more.

Running out of that window is only one of the reasons a machine can be degraded. The others are worth naming, because they need different responses:

A signed-in machine with a perfectly valid record can still have nothing unlocked — a lapsed payment produces exactly that. The row reports the tier it derives from what your account actually grants, so "signed in" and "subscribed" never get conflated.

Check	Can report	Fix action	Guidance
Sign-in / entitlement	pass · info	Sign in	sign in from Settings ▸ Account to unlock Pro / Ultra features

Agent control planes

The last group is not about health either. Each row reports the live state of one switch governing what agents may do unattended, and every one of them is an info row when off — a plane you turned off is a decision, not a fault, and flagging it red would train you to "fix" your own safety choices. The fix action on each row opens the card that owns them all, at Settings ▸ Terminals ▸ Agent control planes.

What each plane governs, and why the switches exist at all, is on Autonomy and controls. Two things about the rows are specific to Doctor:

• Where the truth lives differs by plane. The window and terminal planes read a live value from the running app, so their rows can report states the configuration alone would not reveal: on but PAUSED (the plane is enabled and refusing everything, which is exactly the situation someone debugging needs to see), and status unavailable — rebuild pending on a build that predates the status command. The terminal plane's pause has its own control in the Terminals view; the row links you there. The calendar, email-sending, and knowledge-graph-write planes read their configured value, which for them is the live effect.
• One plane also stops you. With Email sending off, your own composer's Send is refused too — not only an agent's. That is deliberate and it is the single most misread failure on this board, so if your Send button stops working while drafts still save and reads are fine, this row is the first place to look.

Check	Can report	Fix action	Guidance
Window & view control	pass · info	Open control planes	—
Terminal control	pass · info	Open control planes	—
Calendar control	pass · info	Open control planes	—
Email sending	pass · info	Open control planes	—
Knowledge-graph writes	pass · info	Open control planes	—

When the app will not start

The same checks exist as a zero-dependency terminal script that needs no daemons and no Python packages: run python scripts/doctor.py from your install root. Its companion is python scripts/provision_runtime.py, the command-line form of the Runtime group's Provision button.

Both are fallbacks for the rare case where the desktop app cannot boot at all. When the app does open, use the buttons — see Troubleshooting for the full escalation path.