health-check

Purpose

Diagnose what's working, what's broken, and fix what can be fixed. This is Dex's self-repair system. It reads health data from pre-flight checks and error logs, translates technical failures into plain language, and offers specific fixes.

When to Run

• User types /health-check
• User says "fix health issues" or "something's broken"
• User says "check health" or "system status"
• After session start shows pre-flight warnings
• When an MCP tool fails and user wants to investigate

Execution

Step 1: Gather Health Data

Read both health files silently. Don't show raw JSON to the user.

A. Pre-flight results:

Read: .logs/mcp-health.json

This file contains cached results from the last pre-flight check. Each server entry has:

• status: "ok" or "error"
• error: technical error message (for your diagnosis)
• humanError: plain-language message (for the user)
• checkedAt: when it was last checked

B. Error queue:

Read: .logs/error-queue.json

This file contains recent errors from MCP tool calls. Each entry has:

• source: which MCP server (e.g., "mcp:work-mcp")
• severity: "error" or "warning"
• message: technical error (for your diagnosis)
• humanMessage: plain-language message (for the user)
• context.tool: which tool was called
• timestamp: when it happened
• count: how many times (deduped within 5-minute windows)
• acknowledged: whether user has been told about it

C. If either file is missing:

If .logs/mcp-health.json doesn't exist, the pre-flight checker hasn't run yet. Note this and offer to run one.

If .logs/error-queue.json doesn't exist, there are no logged errors. This is good news.

If the .logs/ directory doesn't exist at all, the health system hasn't been set up yet. Tell the user:

The health monitoring system isn't set up yet. This is normal if you just updated Dex.

Want me to check your MCP servers manually? I can verify each one is working.

Then skip to Step 5 (manual check).

Step 2: Display Health Summary

Present results in plain language, grouped by severity. Never show raw JSON or stack traces.

If everything is healthy and no unacknowledged errors:

All systems are running fine. Nothing to fix.

Last checked: [relative time, e.g., "2 hours ago"]
MCP servers: [X]/[Y] operational
Recent errors: None

Stop here. Don't pad with unnecessary detail.

If there are issues, show them grouped by severity:

Dex Health Report
━━━━━━━━━━━━━━━━

ERRORS (need attention)

  1. [Server name] — [humanMessage or humanError]
     When: [relative time]  |  Occurrences: [count]
     Tool affected: [tool name, if from error queue]

  2. [Server name] — [humanMessage or humanError]
     When: [relative time]  |  Occurrences: [count]

WARNINGS (worth knowing)

  3. [Server name] — [humanMessage or humanError]
     When: [relative time]

━━━━━━━━━━━━━━━━
[X] issues found  |  [Y] can be auto-fixed

Formatting rules:

• Show errors first, then warnings
• Use the humanMessage or humanError field — never the technical message or error
• Show relative timestamps ("2 hours ago", "yesterday at 3pm") not ISO timestamps
• If count > 1, show it — "Occurrences: 5" tells the user this is a persistent problem
• Combine pre-flight failures and error queue entries for the same server into one item
• Cap display at 10 issues. If more: "...and [N] more. Want to see all?"

Step 3: Diagnose and Propose Fixes

For each issue, analyze the technical message/error field (not shown to user) and propose a specific fix. Use this mapping:

Module/Package Issues:

Config Issues:

File/Permission Issues:

Connection Issues:

Catch-all:

Present fixes as a numbered list tied to each issue:

Recommended fixes:

  1. Granola MCP — missing package
     → Run: pip install -e dex-core
     [Auto-fixable]

  2. Work MCP — task file not found
     → Want me to check if 03-Tasks/Tasks.md exists?
     [Needs investigation]

  3. Career MCP — permission error on evidence file
     → Run: chmod 644 05-Areas/Career/Evidence/2026-Q1.md
     [Manual fix]

Step 4: Offer to Fix

After showing the diagnosis, offer to take action:

Want me to try fixing these? Here's what I can do:

  Auto-fix (I'll handle it):
  • Reinstall Python packages
  • Regenerate missing config from example
  • Create missing vault files (Tasks.md, etc.)
  • Validate and repair .mcp.json

  Manual (you'll need to do this):
  • File permission changes
  • Editor restart
  • API key configuration (/ai-setup)

[Fix what you can] / [Show me details first] / [Skip for now]

If user says "fix what you can":

Execute auto-fixable items in order:

1. Missing packages: Run pip install -e dex-core from the dex-core directory
2. Missing .mcp.json: Copy from .mcp.json.example, substitute VAULT_PATH
3. Invalid .mcp.json: Read it, validate JSON, identify the issue, offer to rewrite
4. Missing vault files: Create with minimal valid content (e.g., empty Tasks.md with headers)
5. Corrupted JSON data files: Read the file, identify the corruption, offer to reset or repair

After each fix, report:

✓ Reinstalled Python packages
✓ Created missing 03-Tasks/Tasks.md
✗ Couldn't fix permission on Evidence file — you'll need to run:
  chmod 644 05-Areas/Career/Evidence/2026-Q1.md

If user says "show me details first":

For each issue, show the full technical context (this is the one time you show technical detail):

Issue #1: Granola MCP — missing package

  Technical error: ModuleNotFoundError: No module named 'granola_server'
  Server config: dex-granola-mcp in .mcp.json
  Last working: 2 days ago

  Fix: pip install -e dex-core

  This reinstalls all MCP server packages. It takes about 10 seconds.

Step 5: Acknowledge Errors

After addressing issues (whether auto-fixed or explained):

Update the error queue:

Read .logs/error-queue.json, set acknowledged: true on every entry that was shown to the user. Write the file back.

This prevents the same errors from resurfacing at the next session start.

Note: If the error queue file doesn't exist or is empty, skip this step.

Step 6: Fresh Re-Check (Optional)

At the end, offer a fresh check:

Want me to run a fresh pre-flight check to verify everything?

If yes:

1. Delete .logs/mcp-health.json (forces re-check)
2. Run the pre-flight checker:
   bashCopy

   python3 "$VAULT_PATH/dex-core/core/utils/preflight.py" 2>/dev/null || python3 "core/utils/preflight.py" 2>/dev/null
   

3. Read the newly generated .logs/mcp-health.json
4. Report results:
   Copy

   Fresh check complete:
   
   ✓ work-mcp — OK
   ✓ calendar-mcp — OK
   ✓ career-mcp — OK
   ✗ granola-mcp — still failing (missing package)
   ✓ dex-improvements-mcp — OK
   ...
   
   [X]/[Y] MCP servers operational
   

If the pre-flight script doesn't exist yet (health system not fully built):

Fall back to manual checks:

# For each server in .mcp.json, try importing the module
python3 -c "import core.mcp.work_server" 2>&1
python3 -c "import core.mcp.calendar_server" 2>&1
# etc.

Report which imports succeed and which fail.

Step 7: Track Usage (Silent)

Update System/usage_log.md to mark health check as used.

Analytics (Silent):

Call track_event with event_name health_check_completed and properties:

• errors_found: number of errors found
• warnings_found: number of warnings found
• auto_fixed: number of issues auto-fixed

This only fires if the user has opted into analytics. No action needed if it returns "analytics_disabled".

Edge Cases

No Health Files Exist

The health system hasn't been set up yet. This is expected for new or recently updated Dex installations.

Offer to do a manual check of MCP servers by testing imports, then report what's working.

Error Queue is Very Large

If error-queue.json has more than 20 unacknowledged entries:

There are [N] unacknowledged errors in the queue. Here are the most recent 10:

[Show top 10 by timestamp]

The older errors are likely symptoms of the same issues. Want me to acknowledge them all after we fix the root causes?

Same Server Appears in Both Files

If a server has both a pre-flight failure AND error queue entries, combine them:

Granola MCP — can't start (missing package)
  Pre-flight: Failed to import at [time]
  Also: 3 tool errors since [time] (task creation, task update, etc.)
  Root cause: Missing Python package — fixing the import will resolve the tool errors too

All Servers Healthy but Errors Exist

This means servers started fine but tools failed during use. Focus on the error queue:

All MCP servers are starting correctly, but some tools had errors recently:

  1. Work MCP — task creation failed (3 times, yesterday)
     This might be a data issue rather than a server problem.
     Want me to investigate the task file?

User Just Wants Quick Status

If user says "is everything working?" or "quick health check":

Give the short version only:

MCP Servers: [X]/[Y] operational
Recent errors: [N] (or "None")
[One-liner about any critical issue, or "Nothing needs attention."]

Don't go into fix mode unless asked.

Granola Check

Granola meeting sync uses the desktop app's stored credentials automatically. As part of the health check, verify that Granola's credentials file exists (supabase.json in Granola's app data directory). If missing, note that Granola isn't installed or the user isn't signed in.

Related Commands

• /ai-status — Check AI model configuration specifically
• /ai-setup — Configure API keys and model preferences
• /dex-update — Update Dex (often fixes package issues)
• /xray — Understand how Dex's architecture works under the hood