Profiles Doctor

A read-only scanner with an optional repair mode for broken config, orphaned plugins, and alias collisions.

Opening Doctor

Two ways in:

• App settings (top-right of the drag bar), then Open Doctor.
• Configure Claude, Health tab, Open in Doctor next to any finding.

Modes

Detect mode

Read-only. Doctor scans every file it knows about and reports findings, each with a severity of healthy, warning, or error. Nothing on disk is touched.

Repair mode

For findings Doctor knows how to fix, it offers a Repair button. Repairs are opt-in per finding. Before writing any change, Doctor creates a timestamped backup by copying the original file to <file>.bak-<YYYYMMDD-HHMMSS> in the same directory.

What Doctor checks

profiles.json

• The file exists and parses as JSON.
• Every profile has a valid name that maps to a directory.
• Every profile's configDir exists on disk.

teams.json

• The file parses.
• Every team's lead profile still exists.
• Every team member references a real profile.

installed_plugins.json

• The file parses.
• The shape matches the expected { plugins: {...} }.
• Every referenced cache directory exists under ~/.claude/plugins/cache/.

Profile references

• Every plugin a profile enables is actually installed.
• Every disabled MCP server still exists in the source (~/.claude.json or project .mcp.json).
• Every excluded item has a valid source plugin.

Aliases

• No duplicate alias names across profiles.
• Every alias script in ~/.claudeworks/bin/ traces back to a real profile.
• Orphaned alias scripts are flagged (profile deleted but script remains).

Symlinks

• Every profile's symlinks into ~/.claude/plugins/cache/ point at a real target.
• Broken symlinks are flagged.

Export diagnostics

From Doctor, click Export Diagnostics to write a sanitised snapshot of every finding. Safe to attach to a bug report. Personal paths, API keys, and env var values are stripped.

What Doctor won't do

• Install missing plugins. Use the marketplace for that.
• Overwrite your CLAUDE.md or workflow contents.
• Delete profiles you haven't explicitly asked to remove.