From ai-brain-starter
Diagnoses AI Brain Starter vault health: verifies CLAUDE.md, Meta folder, skills, hooks, journal index, MCPs, .ps1 BOM/em-dash issues, and git freshness. Prints green/yellow/red terminal report.
npx claudepluginhub adelaidasofia/ai-brain-starter[vault path, defaults to $VAULT_PATH or current directory]This skill uses the workspace's default tool permissions.
Tells you whether your second brain is healthy.
Audits .claude/ directory for config hygiene, junk files, .gitignore completeness, naming consistency, cache size; syncs plugins and detects version drift. Outputs health report with fix commands.
Runs comprehensive diagnostics on Claude Code environment: plugins, settings, hooks, MCP servers. Identifies issues, supports --fix and --verbose.
Generates read-only diagnostic report for bedrock vaults: verifies setup and graphify-out integrity, detects orphan entities, dangling content, old files (>15 days).
Share bugs, ideas, or general feedback.
Tells you whether your second brain is healthy.
Most "Claude is broken" reports trace to one of:
journal-index.json stale or malformed, so insights find nothing.ps1 files lost their UTF-8 BOM, so Windows PowerShell crashes/diagnose checks all of these in ~5 seconds. It writes nothing, sends no network requests beyond a single git fetch, and exits with a status code so it can be wired into CI or cron.
Find the script. On the maintainer machine: ~/Desktop/ai-brain-starter/scripts/diagnose.sh. On an end-user install: ~/.claude/skills/ai-brain-starter/scripts/diagnose.sh.
Run it. Pick the right one for the platform:
Mac / Linux:
bash ~/.claude/skills/ai-brain-starter/scripts/diagnose.sh
# or pass an explicit vault:
bash ~/.claude/skills/ai-brain-starter/scripts/diagnose.sh "/path/to/vault"
Windows:
pwsh ~/.claude/skills/ai-brain-starter/scripts/diagnose.ps1
# or:
pwsh ~/.claude/skills/ai-brain-starter/scripts/diagnose.ps1 -Vault "C:\path\to\vault"
By default it uses $VAULT_PATH if set, else the current directory.
Read the output to the user in plain language. Don't dump the raw report unless they ask. Translate:
| # | Check | If FAIL | If WARN |
|---|---|---|---|
| 1 | CLAUDE.md present + has Vault Map | Re-run /setup-brain Phase 4 | Add the Vault Map section by hand |
| 2 | ⚙️ Meta/ + scripts/ + rules/ present | Re-run /setup-brain Phase 3 | Create the missing subfolder |
| 3 | ai-brain-starter + daily-journal skills installed | Re-run bootstrap | Install the missing skill from its phase |
| 4 | Hooks registered + graph-context-hook parses | Phase 5 wires hooks; bash -n the script | - |
| 5 | journal-index.json valid + fresh | Delete and rebuild via build-journal-index.py | Re-run /weekly to refresh |
| 6 | git, python3 (jq optional) on PATH | brew install / winget install | Optional tools missing |
| 7 | Vault is a git repo | - | Recommend git init for snapshot history |
| 8 | All .ps1 have BOM, no em dashes, parse clean | Fix the parser error | Add BOM and strip em dashes (see SKILL.md notes) |
| 9 | MCP config valid JSON | Fix the JSON | No MCPs registered (fine if intentional) |
| 10 | ai-brain-starter up to date with origin/main | Re-clone | git pull in ~/.claude/skills/ai-brain-starter |
If the diagnose run finds that ~/.claude/.ai-brain-starter-email-on-file does not exist, surface this to the user as a yellow finding:
"I noticed you have not completed the Mycelium install form yet. It is a one-time thing, takes about 4 minutes, and means you will get updates when the system improves and help if anything breaks. Want me to open the form now?"
If they say yes, open https://myceliumai.co/install (or /es/install for Spanish) in their browser via the platform open / xdg-open / start command, wait for them to paste the token from their welcome email, then run TOKEN=<token> bash ~/.claude/skills/ai-brain-starter/bootstrap.sh. After bootstrap finishes, continue the diagnose flow.
This is a second surface for the email gate (the first being scripts/email-gate-hook.py which fires on UserPromptSubmit). Some users run /diagnose after a problem and never trigger the hook; this catches them.
/diagnose output into a gh issue or anywhere public — it includes home directory paths.