olakai-monitor-doctor

Self-Heal Local Coding Agent Monitoring

This skill diagnoses and repairs already-installed hooks-based monitoring for a local coding tool (Claude Code, Codex CLI, Cursor). Use it when monitoring seems broken: no events, missing KPIs, a deleted/404 agent, or a clobbered config.

First-time setup? Use olakai-monitor-local-coding-agent instead — it covers init, what each tool captures, and KPI configuration. This skill is the repair half.

CLI requirement: monitor list, monitor doctor, monitor repair, and agents mine require olakai-cli ≥ 0.7.0. Older CLIs only have init / status / disable. Upgrade: npm install -g olakai-cli@latest.

The three commands, in order

If your monitoring seems broken, drive these in order. Always start with monitor list, then monitor doctor, then escalate to repair.

# 1. SEE — machine-wide picture: what's installed, where, and which entries are drifting.
olakai monitor list

# 2. DIAGNOSE — ordered health-check chain for the current workspace + tool.
olakai monitor doctor --tool claude-code         # or codex / cursor
olakai monitor doctor --all                       # every workspace on this machine

# 3. FIX — idempotent, best-effort auto-repair of what doctor flagged.
olakai monitor doctor --tool claude-code --fix

# 4. ESCALATE — forceful re-init that preserves agent linkage (heals a clobbered config).
olakai monitor repair --tool claude-code

Two lenses: machine vs account

Two distinct questions, two distinct commands. Keep them straight.

Question	Lens	Command	Source of truth
"What is monitored on THIS machine, and where?"	Machine	olakai monitor list	Local registry at ~/.olakai/registry.json
"What coding agents exist across my whole account?"	Account	olakai agents mine	Olakai backend (cross-machine)

The backend has no scope model — agents are account-scoped only, with no per-repo / per-workspace / per-host fields. So "where am I monitoring?" is a purely machine-local fact that nobody persists server-side; the CLI records it in ~/.olakai/registry.json, which monitor list reads. monitor doctor bridges the two lenses — it flags drift between the registry, the backend, and what's actually on disk.

olakai monitor list                              # MACHINE: every monitored workspace, grouped by tool
olakai monitor list --json
olakai agents mine                               # ACCOUNT: your coding agents across the whole account
olakai agents mine --source claude-code          # filter to one tool
olakai agents mine --source codex --json

What each doctor check means

monitor doctor runs an ordered chain — each step gates the next, so the first failure is usually the real problem:

#	Check	PASS means	A FAIL points to
1	registry-entry	This workspace is recorded in ~/.olakai/registry.json	Never inited here, or registry wiped → --fix adopts the on-disk config into the registry
2	config-valid	.olakai/monitor-<tool>.json exists and parses (key, agentId, endpoint)	Missing/corrupt config → monitor repair re-writes it
3	hooks-installed	The tool's settings file has the Olakai hook entries	Hooks removed or a settings edit clobbered them → --fix re-merges them
4	api-key-valid	The stored key authenticates (GET /api/monitoring/prompt/me)	Key revoked/rotated → --fix rotates a fresh key on the same agent and rewrites the config (cross-wired-key detection is a monitor init feature, not doctor)
5	agent-exists	The linked agent still exists on the backend	Agent deleted (404) → recreation is gated behind --recreate-missing or repair (so a transient 404 can't spawn a duplicate)
6	events-flowing	Recent events exist for this agent (metadata probe)	Hooks installed but never fired → run a turn, then re-check; if still empty see the unattributed-activity caveat below

--fix is idempotent and best-effort: it adopts the registry entry, re-merges missing hooks, and re-links a rejected key. It will not recreate a missing agent unless you add --recreate-missing — a deliberate guard against a flaky/transient 404 spawning a duplicate agent.

Decision tree

Want the machine-wide picture ("what's monitored here")?
└── olakai monitor list   (account-wide instead? → olakai agents mine)

No events appearing?
└── olakai monitor doctor --tool <tool>      ← always start here
    ├── registry-entry FAIL  → olakai monitor doctor --tool <tool> --fix   (adopts config into registry)
    ├── hooks-installed FAIL → olakai monitor doctor --tool <tool> --fix   (re-merges hooks)
    ├── api-key-valid FAIL   → olakai monitor doctor --tool <tool> --fix   (re-links a fresh key)
    ├── agent-exists FAIL (404)
    │   ├── olakai monitor repair --tool <tool>                  (recommended — preserves linkage)
    │   └── olakai monitor doctor --tool <tool> --fix --recreate-missing
    └── events-flowing FAIL  → run one turn, re-check; Codex/Cursor in an un-inited repo
                               → silent-exit (see unattributed-activity caveat)

Config clobbered / settings file edited by hand / legacy layout?
└── olakai monitor repair --tool <tool>
    (always re-merges hooks, migrates legacy config, re-links key only if invalid,
     recreates the agent only on a TRUE 404 — never duplicates a healthy agent)

doctor --fix vs repair — when to use which

	monitor doctor --fix	monitor repair --tool <t>
Intent	Surgical: fix only what a check flagged	Forceful re-init that preserves agent linkage
Hooks	Re-merges only if hooks-installed failed	Always re-merges (heals a clobbered settings file)
Legacy config	—	Migrates legacy config layout
API key	Re-links only if invalid	Re-links only if invalid
Missing agent	Recreates only with --recreate-missing	Recreates only on a true 404
Use when	Doctor told you exactly what's wrong	"Just make it work again" / settings got mangled

Scope honesty (why some sessions aren't tracked)

Where the hooks live differs by tool, and that drives what gets attributed:

Tool	Hook scope	Where hooks are written
Claude Code	Workspace	.claude/settings.json (this workspace only)
Codex CLI	Global	~/.codex/config.toml (all workspaces)
Cursor	Global	~/.cursor/hooks.json (all workspaces)

For all three, the per-workspace .olakai/monitor-<tool>.json holds the agent linkage (key + agent ID + endpoint).

⚠️ Unattributed-activity caveat (Codex / Cursor). Because Codex and Cursor hooks are global, they fire in every workspace — including ones you never ran init in. When the hook fires in a workspace with no .olakai/monitor-<tool>.json, it silently exits and that session is NOT attributed to any agent (no event). This is expected: a global hook with no local linkage has nowhere to report. If you expect Codex/Cursor activity from a repo and see none, the most common cause is you never ran olakai monitor init --tool <tool> in that repo. Run olakai monitor list to see which workspaces are linked, and olakai monitor doctor --tool <tool> for an in-context explanation.

Claude Code does not have this caveat — its hooks are workspace-scoped, so they only fire where you installed them.

Common scenarios

"No events from my coding tool"

olakai monitor doctor --tool <tool>     # read the first failing check
olakai monitor doctor --tool <tool> --fix   # auto-repair registry/hooks/key

If events-flowing is the only failure: run one real turn and re-check. For Codex/Cursor, confirm you ran init in this repo (global-hook silent-exit otherwise).

"My monitored agent disappeared / doctor says 404"

olakai monitor repair --tool <tool>                          # recommended — recreates only on a true 404
# or explicitly:
olakai monitor doctor --tool <tool> --fix --recreate-missing

"Hooks stopped firing after a tool update (esp. Cursor)"

olakai monitor repair --tool cursor     # re-merges hook entries, preserves the agent
cursor --version                        # confirm >= 1.7

"I edited my settings file by hand and broke it"

olakai monitor repair --tool <tool>     # always re-merges hooks + migrates legacy config

Validate the fix (Golden Rule)

After repairing, confirm with a real event:

# 1. Run one turn in the coding tool
# 2. Fetch the latest event
olakai activity list --agent-id AGENT_ID --limit 1 --json
# 3. Inspect it
olakai activity get EVENT_ID --json | jq '{source, customData, kpiData}'

Confirm: event exists with a recent timestamp; source matches your --tool; prompt/response/tokens/modelName are populated; kpiData shows numbers (not strings or nulls). Find AGENT_ID via olakai monitor status --tool <tool> or olakai monitor list.

Debug mode

When doctor passes but events still seem off, watch the dispatcher directly:

export OLAKAI_MONITOR_DEBUG=1           # then run a turn
# Inspect /tmp/olakai-monitor-debug-<pid>.log for:
#   dispatcher/posting    — payload about to be posted
#   dispatcher/posted     — HTTP status + 500-byte response preview
#   dispatcher/post-error — error details if the POST failed
#   transcript-read-failed / transcript-parsed — transcript parsing signals

Quick Reference

# See (two lenses)
olakai monitor list [--json]                                 # MACHINE: what's monitored here + drift
olakai agents mine [--source claude-code|codex|cursor] [--json]   # ACCOUNT: agents across the account

# Diagnose + repair
olakai monitor doctor --tool <tool> [--fix] [--recreate-missing]
olakai monitor doctor --all [--fix]                          # every workspace on this machine
olakai monitor repair --tool <tool>                          # forceful re-init, preserves agent

# Agent lifecycle (account-wide; requires current backend)
olakai agents archive AGENT_ID [--unarchive]
olakai agents rename AGENT_ID "New Name"
olakai agents delete AGENT_ID

# Debug
export OLAKAI_MONITOR_DEBUG=1

Related skills

• olakai-monitor-local-coding-agent — first-time setup (init), per-tool capture details, KPI configuration.
• olakai-troubleshoot — generic SDK / KPI / event diagnostics (string KPIs, null KPIs, customData pipeline) not specific to a coding tool.