intutic doctor

Runs a series of health checks to verify that all Intutic components are properly configured and reachable. Each check prints ✓ or ✗ with a one-line remediation if something is wrong.

Usage

intutic doctor

No flags. The command reads ~/.intutic/ and the workspace recorded by intutic init.

Checks

The doctor runs these checks in order. Checks 2–5 need a control plane: on a machine with no login they are skipped with one note, and the proxy and CA-trust remediations point at intutic start. On such a machine check 8 reads the snapshot intutic gates install wrote, and check 9 runs; both point at intutic gates install to fix what is missing. Check 10 runs only when a SOP sets plan_approval:. Check 12 always runs.

#	Check	What it verifies	Pass condition
1	Proxy	GET http://127.0.0.1:4000/health (the port of INTUTIC_PROXY_URL when set)	HTTP 200 within 3s
2	Control Plane Auth	GET {controlPlaneUrl}/api/v1/auth/me with the stored credentials from intutic login	Any response other than 401/403 within 5s
3	Sync Daemon	PID file at ~/.intutic/daemon.pid, or a process scan	Process is alive
4	Harness Configs	SHA-256 of each governed harness file against <workspaceRoot>/.intutic/integrity.json, which intutic connect writes	Every file present and unchanged
5	Daemon Log	The first readable of ~/.intutic/logs/sync-daemon.log, the system-service log (/Library/Logs/Intutic/sync-daemon.log on macOS, /var/log/intutic/sync-daemon.log on Linux), then the legacy ~/.intutic/daemon.log	Readable and not empty; the age of the newest entry is shown
6	Valkey	TCP connection to 127.0.0.1:6379	Connects within 2s
7	Cert Trust	~/.intutic/ca.crt exists and is in the OS trust store	macOS: security verify-cert; Linux: system CA directory
8	Policy Snapshot	~/.intutic/hooks/policy-snapshot.rules, the compiled workspace policy every harness gate reads	Present, digest valid, belongs to the logged-in workspace (a local snapshot names none), at least one rule, refreshed within 7 days
9	Local Gates	With no login: a gate file for each harness recorded by intutic init that has a tool-call gate	Every such harness has one
10	Plan Approval	Only when a SOP sets plan_approval:. With no login there is no control plane to approve a plan, so every gated call that is not a read is refused (PLAN_NOT_APPROVED). With one, the approved-plans cache the daemon writes (~/.intutic/hooks/approved-plans.jsonl)	A control plane is connected and the cache has not expired
11	Cisco Skill Scanner	Whether the optional skill-scanner binary used by intutic skill audit --engine cisco is on PATH	Always passes; prints the install command when absent
12	Decide	With no decide rule in the snapshot and no engine configured, one passing line: Decide — no decide rules and no engine configured. Otherwise one line each: Decide Engine (the engine and its model, with the digest; Decide Model Digest when the server cannot report a weights digest), Decide Canary (the known-answer canary, cached in ~/.intutic/decide/canary.json), Decide Latency (the per-call p95 of 20 warm calls, stored in ~/.intutic/decide/engine.json), Decide Budget (each harness and rule pair whose time budget the rule cannot fit; such a rule escalates there instead of being asked) and Decide Rules (how many rules, and how many enforce on this model)	The engine answers, the canary passes, and every rule fits every harness's budget

Valkey is optional for a standalone proxy (intutic start runs without it), so a failed Valkey check on a machine that never set one up is expected. A stale policy snapshot is still enforced; the check fails because nothing has refreshed it in over a week.

The command exits 0 whether or not checks fail, so read the summary line rather than the exit status.

Example output

Intutic Doctor — Workspace Health Check

  ✓ Proxy — Reachable at http://127.0.0.1:4000/health (HTTP 200)
  ✓ Control Plane Auth — Authenticated at https://your-control-plane.example
  ✓ Sync Daemon — Running (PID 42156)
  ✓ Harness Configs — 3 file(s) intact — no drift detected
  ✓ Daemon Log — Readable at /Users/dev/.intutic/logs/sync-daemon.log (847 lines, last entry 2m ago)
  ✓ Valkey — Reachable at 127.0.0.1:6379 (direct TCP probe)
  ✓ Cert Trust — CA cert exists and is trusted by macOS Keychain
  ✓ Policy Snapshot — 9 rule(s), digest a1b2c3d4e5f60718293a4b5c6d7e8f90, 0d old
  ✓ Cisco Skill Scanner — not installed (optional integration)
    → pipx install cisco-ai-skill-scanner
  ✓ Decide — no decide rules and no engine configured

✔ All 10 checks passed — workspace is healthy.

On a machine with no login, with the gates installed:

  ✗ Proxy — Not reachable — fetch failed
    → Start the proxy: ensure `intutic start` is running or the proxy binary is started.
  ✗ Valkey — Not reachable on port 6379
    → Start Valkey: `docker compose up -d valkey` or install locally.
  ✗ Cert Trust — CA certificate not found at /Users/dev/.intutic/ca.crt
    → Start the proxy with `intutic start` — it auto-generates the CA cert on first run.
  ✓ Policy Snapshot — 31 rule(s), digest 0f3c9a7e21d84b6a5c0e9f1d2b3a4c5d, 0d old
  ✓ Local Gates — 2 gate(s) installed: claude-code, cursor
  ✓ Cisco Skill Scanner — not installed (optional integration)
    → pipx install cisco-ai-skill-scanner
  ✓ Decide — no decide rules and no engine configured
  – Control plane, sync daemon, harness sync and daemon log checks skipped: open core, no control plane connected. The gates are checked as `intutic gates install` writes them.

When a check fails:

  ✗ Proxy — Not reachable — fetch failed
    → Start the proxy: ensure `intutic connect` is running or the proxy binary is started.
  ✗ Sync Daemon — Not running
    → Start with `intutic connect` or install as a service with `intutic daemon install`.

Remediation commands

Check	Fix
Proxy not reachable	intutic start (standalone) or intutic connect
No credentials	intutic login
Auth failed (401/403)	intutic login (re-authenticate)
Daemon not running	intutic connect or intutic daemon install
No workspace config	intutic init
No integrity data, or config drift detected	intutic connect (writes the configs and auto-corrects drift)
Daemon log not found	Start the daemon first with intutic connect
Valkey not reachable	docker compose up -d valkey or install locally (optional for a standalone proxy)
CA cert not found	intutic connect (auto-generates on first run)
CA cert not trusted (macOS)	sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ~/.intutic/ca.crt
CA cert not trusted (Linux)	sudo cp ~/.intutic/ca.crt /usr/local/share/ca-certificates/intutic-ca.crt && sudo update-ca-certificates
Policy snapshot absent, invalid, empty or stale	intutic gates install with no login; intutic policy snapshot with one
Local gates missing	intutic gates install
Plan approval with no control plane connected	Remove plan_approval: from the local SOP, or connect a workspace with intutic connect and capture plans there
No approved-plans cache	Start the daemon with intutic connect; its key needs the traces:read scope to read approved plans
Cisco skill scanner not installed	pipx install cisco-ai-skill-scanner (only needed for --engine cisco)
Decide engine not configured	intutic decide configure --url <url> --model <model>; intutic decide models lists what was validated
Decide engine unreachable or its model missing	Start the engine, or pull the model it names
Decide model digest weak	Set INTUTIC_DECIDE_MODEL_DIGEST to the weights digest
Decide canary failed	The model answers the fixed known-answer questions wrongly: check the model and adapter
Decide budget: a rule cannot fit a harness	Ask fewer questions, raise --parallel on an engine that serves requests concurrently, or use a faster model

Source

• doctor.ts