Matrix Doctor

Run comprehensive diagnostics on the Matrix plugin and automatically fix issues when possible.

What It Does

1. Checks Matrix Directory: Verifies ~/.claude/matrix/ exists and is writable
2. Checks Database: Tests connection, validates schema version
3. Checks Configuration: Validates config file, checks for missing sections
4. Checks Hooks: Verifies hooks are installed correctly
5. Checks Code Index: Confirms repository is indexed
6. Checks Repo Detection: Tests fingerprinting works

Auto-Fix Capabilities

The doctor will automatically attempt to fix:

• Missing Matrix directory (creates it)
• Database connection issues (reinitializes)
• Invalid/missing configuration (resets to defaults)
• Missing code index (triggers reindex)

Usage

Call the matrix_doctor tool with:

• autoFix: true (default) - Attempt to fix issues automatically
• autoFix: false - Only run diagnostics without fixing

If Issues Cannot Be Fixed

If the doctor finds issues that cannot be automatically fixed:

1. A GitHub issue template will be generated
2. The user should be directed to open an issue at: https://github.com/ojowwalker77/Claude-Matrix/issues/new?template=bug_report.md
3. Include the full diagnostic output in the issue

Expected Output

The tool returns a DoctorResult object containing:

• healthy: boolean indicating overall health
• checks: array of diagnostic results
• environment: OS, Bun version, paths
• suggestions: array of recommended actions
• issueTemplate: pre-filled GitHub issue template (if issues found)