Skip to main content
command CX Codex

doctor · rohitg00 — Claude Code command: configuration diagnostic

doctor scans your pro-workflow and Claude Code setup: checks hooks, database, context usage, MCP servers, and git state. Spots broken hook scripts and settings conflicts before they cause problems.

MIT ★ 2,966 updated 2026-09-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add rohitg00/pro-workflow
/plugin install pro-workflow@pro-workflow
Open on GitHub

What doctor does

The doctor command runs a full diagnostic suite. It verifies that pro-workflow commands are in place, the database is accessible, and hooks are active and working. Each hook—commit-validate, secret-scan, git-blast-radius—gets tested on both valid and invalid inputs; all should return OK.

It also measures context usage (alert at 70–90%, critical above 90%), counts CLAUDE.md lines (split if over 150), tallies active MCP servers (aim for under 10), checks git status and uncommitted changes, and flags conflicts between project-level and user-level settings.json. Wiki and council status show without exposing environment values.

Finally, it outputs a summary: installation status, hook state, context percentage, MCP count, and CLAUDE.md size. Any failure gets a quick-fix table—from copying commands to disabling unused servers.

What it helps with

  • Verify hook scripts are active and blocking unsafe git and secret operations
  • Find conflicts between project and user settings before they interfere
  • Monitor context and CLAUDE.md size ahead of heavy sessions
  • Confirm pro-workflow installation and database availability
  • Troubleshoot inactive hooks or incorrect script paths

Example prompts for the agent

  • Run /doctor before critical commits to ensure hooks catch dangerous patterns
  • Use /doctor if context feels sluggish or Claude behaves unexpectedly
  • Call /doctor after updating pro-workflow to verify nothing broke

How to install doctor

1Plugin marketplace

/plugin marketplace add rohitg00/pro-workflow
/plugin install pro-workflow@pro-workflow

2Manually: put the files in place

.claude/commands/pro-workflow-doctor.md

The built-in /doctor overrides a file with the same name, so the file is renamed. Call it with /pro-workflow-doctor. For all projects use ~/.claude/commands/

Questions about doctor

How do I install doctor in Claude Code?

Run /plugin marketplace add rohitg00/pro-workflow, then /plugin install pro-workflow@pro-workflow, and point to .claude/commands/pro-workflow-doctor.md.

What does doctor do?

It audits pro-workflow installation, hook status (commit-validate, secret-scan, git-blast-radius), context and CLAUDE.md size, active MCP servers, git state, and settings conflicts. Produces a summary and suggests fixes.

What if doctor says 'Hooks: INACTIVE'?

Hooks aren't firing. Check that hooks.json is in the right location, script paths use ${CLAUDE_PLUGIN_ROOT} or absolute paths, and scripts have execute permissions.

Source text

doctor.md · MIT
---
description: Diagnose pro-workflow setup and Claude Code configuration
---

# /doctor - Configuration Health Check

Run a diagnostic on your pro-workflow and Claude Code setup.

## Check These

### 1. Pro-Workflow Installation
```bash
ls -la ~/.claude/commands/wrap-up.md 2>/dev/null && echo "Commands: OK" || echo "Commands: MISSING"
ls -la ~/.pro-workflow/data.db 2>/dev/null && echo "Database: OK" || echo "Database: MISSING"
```

### 2. Hooks Status
Check if hooks.json is loaded and hooks are active. Run:
```bash
cat ~/.claude/settings.local.json 2>/dev/null | head -5
```

If hooks aren't firing, check:
- hooks.json is in the right location
- Script paths use `${CLAUDE_PLUGIN_ROOT}` or absolute paths
- Scripts have execute permissions

### 2a. Deterministic Hook Sanity
Verify each hook script on both happy and failing inputs:
```bash
# commit-validate: valid passes, bad format blocks (exit 2)
echo '{"tool_input":{"command":"git commit -m \"feat: x\""}}' | node "$CLAUDE_PLUGIN_ROOT/scripts/commit-validate.js" && echo "commit-validate pass: OK"
echo '{"tool_input":{"command":"git commit -m \"not conventional\""}}' | node "$CLAUDE_PLUGIN_ROOT/scripts/commit-validate.js" 2>&1; test $? -eq 2 && echo "commit-validate block: OK"

# secret-scan: clean passes, hardcoded key blocks
echo '{"tool_input":{"content":"hello"}}' | node "$CLAUDE_PLUGIN_ROOT/scripts/secret-scan.js" && echo "secret-scan pass: OK"
echo '{"tool_input":{"content":"key=\"AKIAIOSFODNN7EXAMPLE\""}}' | node "$CLAUDE_PLUGIN_ROOT/scripts/secret-scan.js" 2>&1; test $? -eq 2 && echo "secret-scan block: OK"

# git-blast-radius: safe passes, destructive blocks
echo '{"tool_input":{"command":"git status"}}' | node "$CLAUDE_PLUGIN_ROOT/scripts/git-blast-radius.js" && echo "git-blast-radius pass: OK"
echo '{"tool_input":{"command":"git reset --hard"}}' | node "$CLAUDE_PLUGIN_ROOT/scripts/git-blast-radius.js" 2>&1; test $? -eq 2 && echo "git-blast-radius block: OK"
```
Every line should print an `OK`. Missing any means the script is silently broken.

### 2b. Git Safety Override
If you need to run a blocked git operation deliberately (e.g. intentional
`git reset --hard` during recovery), export `PRO_WORKFLOW_ALLOW_UNSAFE_GIT=1`
for the shell that will run it. Never set it globally.

### 3. Context Health
```text
/context
```
- Usage < 70%: Healthy
- Usage 70-90%: Consider `/compact`
- Usage > 90%: Compact immediately or start fresh

### 4. MCP Servers
Check active MCPs. Target: <10 servers, <80 tools.

### 5. CLAUDE.md Size
```bash
wc -l CLAUDE.md 2>/dev/null || echo "No CLAUDE.md found"
```
- < 60 lines: Ideal
- 60-150 lines: Acceptable
- > 150 lines: Too long, split into modules

### 6. Git Status
```bash
git status --short
git stash list
```
- Uncommitted changes? Commit or stash.
- Stale stashes? Clean up.

### 7. Settings Validation
```bash
cat .claude/settings.json 2>/dev/null | head -3
cat ~/.claude/settings.json 2>/dev/null | head -3
```
- Check for conflicting settings between project and user level
- Verify permission rules are correct

### 8. Wiki Knowledge Base
```bash
node $PRO_WORKFLOW_ROOT/skills/wiki-builder/scripts/wiki-cli.js list 2>/dev/null
node $PRO_WORKFLOW_ROOT/skills/wiki-research-loop/scripts/research-loop.js status 2>/dev/null
ls -1 ~/.pro-workflow/STOP 2>/dev/null && echo "KILL SWITCH ACTIVE — no research runs"
tail -5 ~/.pro-workflow/tick.log 2>/dev/null
```
- List of wikis · seed counts per status · kill-switch state · last cron-tick activity
- Embeddings require an OpenAI or Voyage key configured for this plugin. BM25 search remains local and needs no key. Never print environment values or read credential files.

### 9. Council Providers

In a plugin session, call `run_provider_task` on the `providers` MCP server with `{"task":"council","args":["providers"]}`. It reports configured status without revealing values. The command below is for standalone CLI use.
```bash
node $PRO_WORKFLOW_ROOT/skills/llm-council/scripts/council.js providers 2>/dev/null
```
- Shows which pro-workflow credentials are configured (Anthropic/OpenAI/OpenRouter/Fireworks/custom), without exposing values.

## Quick Fixes

| Issue | Fix |
|-------|-----|
| Commands missing | `cp -r /path/to/pro-workflow/commands/* ~/.claude/commands/` |
| Database missing | `mkdir -p ~/.pro-workflow && npm run build` (in plugin dir) |
| Hooks not firing | Check paths in hooks.json use absolute paths |
| Context degraded | Run `/compact` or start fresh session |
| Too many MCPs | Disable unused: `disabledMcpjsonServers` in settings |
| CLAUDE.md too long | Split into root + package-level files |

## Report

After running checks, summarize:
```text
Pro-Workflow Health Check
  Installation:  OK / NEEDS SETUP
  Hooks:         ACTIVE / INACTIVE
  Context:       XX% (healthy/warning/critical)
  MCPs:          X active (OK / TOO MANY)
  CLAUDE.md:     XX lines (OK / SPLIT RECOMMENDED)
  Git:           clean / X uncommitted files
```

© Rohit Ghumare · MIT · rohitg00/pro-workflow

Similar slash commands

All slash commands for Agent setup: memory, context, orchestration →

doctor by other authors comes first.

doctor Son Nguyen doctor is a Claude Code command that checks connectivity to the Agent Monitor dashboard and probes its APIs. It reports stats and update status in two checks. CX Codex +1 ★ 1,198repo stars maxxing-doctor makushingu The maxxing-doctor skill for Claude Code detects and resolves issues with Harness Maxxing installations. It activates when the UI fails to load, sessions hang, or automated tasks stop running. CX Codex +1 ★ 285repo stars groove-admin-doctor andreadellacorte groove-admin-doctor runs Groove health checks for the repository, versions, companion skills, symlinks, and native hooks. It helps locate setup issues before work starts. CX Codex +1 573installs groove-utilities-task-doctor andreadellacorte groove-utilities-task-doctor audits task-backend setup, command-line access, authentication, and reachability. Use it before relying on task commands in a repository. CX Codex +1 552installs jetson-diagnostic Jetson Team jetson-diagnostic collects a read-only Jetson snapshot covering device identity, memory, GPU, thermal state, power, storage, services and processes. Use it to inspect a live host. CX Codex +1 1,300installs tool-foundation-sprint-readiness product-on-purpose tool-foundation-sprint-readiness is a Claude Code skill that assesses team readiness before a Foundation Sprint and determines whether to run it now, postpone it or close gaps first. Takes 30–45 minutes. CX Codex +1 705installs clinical-diagnostic-reasoning curiositech clinical-diagnostic-reasoning detects cognitive biases in medical decisions, audits differential hypotheses, and structures diagnostic error reviews. Useful during treatment planning and clinical case debriefs. CX Codex +1 178installs

From the same set83

The whole set →
design-engineering The design-engineering skill guides interface animation choices and UI reviews. Use it when refining a component, transition, modal, or other interactive state. CX Codex +1 ★ 2,966repo stars permission-tuner The permission-tuner skill reads permission prompts and auto mode denials from your session logs, then suggests permission rules and autoMode entries to reduce interruptions. CX Codex +1 ★ 2,966repo stars batch-orchestration batch-orchestration decomposes large codebase changes into independent units and runs parallel agents in isolated git worktrees. CX Codex +1 ★ 2,966repo stars insights insights turns your pro-workflow history into numbers: edits per session, rules you actually apply, mistakes that keep coming back. Useful when you want to see where the agent keeps slipping. CX Codex +1 ★ 2,966repo stars thoroughness-scoring thoroughness-scoring rates implementation choices from 1 to 10 and prompts the agent to pick thorough solutions with tests and typing over brittle shortcuts. CX Codex +1 ★ 2,966repo stars skill-optimizer The skill-optimizer skill proposes edits to a SKILL.md based on stored corrections, then checks candidates against held-out examples before accepting changes. CX Codex +1 ★ 2,966repo stars agent-teams agent-teams is a Claude Code skill that coordinates multiple sessions through shared tasks, messaging, and file locks. Teammates work in parallel on separate parts of the codebase. CX Codex +1 ★ 2,966repo stars sprint-status sprint-status tracks parallel Claude Code sessions and prevents confusion by enforcing session headers and standardized status lines. CX Codex +1 ★ 2,966repo stars

Project sponsors

Companies that keep this analytics open