Matrix Doctor
npx machina-cli add skill ojowwalker77/Claude-Matrix/doctor --openclawMatrix Doctor
Run comprehensive diagnostics on the Matrix plugin and automatically fix issues when possible.
What It Does
- Checks Matrix Directory: Verifies ~/.claude/matrix/ exists and is writable
- Checks Database: Tests connection, validates schema version
- Checks Configuration: Validates config file, checks for missing sections
- Checks Hooks: Verifies hooks are installed correctly
- Checks Code Index: Confirms repository is indexed
- 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 automaticallyautoFix: false- Only run diagnostics without fixing
If Issues Cannot Be Fixed
If the doctor finds issues that cannot be automatically fixed:
- A GitHub issue template will be generated
- The user should be directed to open an issue at: https://github.com/ojowwalker77/Claude-Matrix/issues/new?template=bug_report.md
- Include the full diagnostic output in the issue
Expected Output
The tool returns a DoctorResult object containing:
healthy: boolean indicating overall healthchecks: array of diagnostic resultsenvironment: OS, Bun version, pathssuggestions: array of recommended actionsissueTemplate: pre-filled GitHub issue template (if issues found)
Source
git clone https://github.com/ojowwalker77/Claude-Matrix/blob/main/skills/doctor/SKILL.mdView on GitHub Overview
Matrix Doctor runs comprehensive diagnostics on the Matrix plugin and fixes issues automatically when possible. It validates the Matrix directory, database, configuration, hooks, code index, and repo detection to keep Matrix healthy.
How This Skill Works
The tool performs checks across the Matrix Directory (~/.claude/matrix/), Database connection and schema version, Configuration validity, Hooks installation, Code Index status, and Repo Detection. When autoFix is enabled, it will automatically fix missing directories, reinitialize the database, reset invalid configurations, and trigger reindexing as needed.
When to Use It
- User reports Matrix not working or error messages.
- You want a diagnostic sweep before a Matrix upgrade or update.
- Missing or non-writable Matrix directory at ~/.claude/matrix/.
- Database connection issues or schema version problems are suspected.
- Configuration is invalid or missing sections, or hooks/code index issues are suspected.
Quick Start
- Step 1: Run matrix_doctor with autoFix: true to perform diagnostics and auto-fix fixable issues.
- Step 2: Inspect the DoctorResult for overall health, environment, and recommendations.
- Step 3: If issues remain unfixed, open a report at https://github.com/ojowwalker77/Claude-Matrix/issues/new?template=bug_report.md and include the diagnostic output.
Best Practices
- Run with autoFix enabled initially to automatically remediate fixable issues.
- Review the DoctorResult output, especially environment details and suggestions.
- If issues cannot be auto-fixed, use the generated GitHub issue template for reporting.
- Ensure ~/.claude/matrix/ has correct permissions and is writable.
- Test in a safe environment before applying fixes in production.
Example Use Cases
- Diagnose and auto-fix a non-writable Matrix directory.
- Repair a failing database connection and reinitialize the schema.
- Reset an invalid configuration to defaults and re-run diagnostics.
- Reindex the code base when the code index is missing.
- Detect issues and generate a GitHub issue template for non-fixable problems.
