ccc-doctor

$ccc-doctor — Diagnose the Commander install

CC Commander · $ccc-doctor · one probe → paste-ready diagnostic report → the exact next command

When to use / when not to

• Use when Commander skills or hooks misbehave, after an update, or to produce a report for a GitHub issue or support thread.
• Doctor is read-only. Its single write is the consent-gated autoUpdate toggle in Step 4, always backed up and verified.
• To update the plugin, use $ccc-update. To clean junk or add settings keys, use $ccc-tuneup. For this repository's vendor submodules, use $ccc-upgrade.
• $ARGUMENTS: quick (default) runs Steps 1–5; full adds the source-tree drift checks in Step 6.
• In Codex, ask each AskUserQuestion picker as a plain-text question with the same options; the probe runs unchanged and reports Codex rows.

What happens

1. Probe the install and platform (one Bash call)

Run the block below in a single Bash call. It runs under bash regardless of the login shell, never fails on a missing file (every field falls back to n/a), and makes no network call except the version check.

bash -s <<'PROBE'
J() { node -e 'try{const j=JSON.parse(require("fs").readFileSync(process.argv[1],"utf8"));const v=process.argv[2].split(".").reduce((o,k)=>o==null?o:o[k],j);process.stdout.write(v==null?"n/a":String(v))}catch(e){process.stdout.write("n/a")}' "$1" "$2" 2>/dev/null || echo n/a; }
has() { command -v "$1" >/dev/null 2>&1; }
P="$HOME/.claude/plugins"

# Clone root (has .git) and plugin source (has .claude-plugin/plugin.json) are
# different directories: the repo nests the plugin at commander/cowork-plugin/.
CLONE="$P/marketplaces/commander-hub"; [ -d "$CLONE" ] || CLONE="n/a"
PLUGIN_SRC="n/a"
[ "$CLONE" != "n/a" ] && [ -d "$CLONE/commander/cowork-plugin" ] && PLUGIN_SRC="$CLONE/commander/cowork-plugin"

# installed_plugins.json: the executing copy. Its installPath IS the plugin
# source (cache/<mp>/<plugin>/<version>/), with no commander/cowork-plugin wrapper.
INSTALLED_JSON="$P/installed_plugins.json"
INST=$(node -e 'try{const d=JSON.parse(require("fs").readFileSync(process.argv[1],"utf8"));const k=Object.keys(d.plugins||{}).find(k=>k.startsWith("commander@"));const e=k&&[].concat(d.plugins[k])[0];process.stdout.write(e?[k,e.version||"n/a",e.installPath||"n/a"].join("\t"):"not listed\tn/a\tn/a")}catch(e){process.stdout.write("not found or unparseable\tn/a\tn/a")}' "$INSTALLED_JSON" 2>/dev/null)
INSTALLED_KEY=$(printf '%s' "$INST" | cut -f1); INSTALLED_VERSION=$(printf '%s' "$INST" | cut -f2); INSTALLED_PATH=$(printf '%s' "$INST" | cut -f3)
[ "$PLUGIN_SRC" = "n/a" ] && [ -d "$INSTALLED_PATH" ] && PLUGIN_SRC="$INSTALLED_PATH"

# Desktop-managed (account-synced): no clone and no installed_plugins.json
# entry is HEALTHY in this mode. Update path: Desktop settings, not the CLI.
INSTALL_MODE="cli-marketplace"
if [ "$PLUGIN_SRC" = "n/a" ]; then
  INSTALL_MODE="not-found"
  DM=$(/bin/ls -t "$HOME/Library/Application Support/Claude/"local-agent-mode-sessions/*/*/rpm/plugin_*/.claude-plugin/plugin.json 2>/dev/null | head -50 | while read -r f; do
    /usr/bin/grep -q '"name"[[:space:]]*:[[:space:]]*"commander"' "$f" 2>/dev/null && { echo "$f"; break; }; done)
  [ -n "$DM" ] && { INSTALL_MODE="desktop-managed"; PLUGIN_SRC=$(dirname "$(dirname "$DM")"); }
fi

PLUGIN_VERSION=$(J "$PLUGIN_SRC/.claude-plugin/plugin.json" version)
NODE_VER=$(node --version 2>/dev/null || echo n/a)
OS_INFO=$(uname -srm 2>/dev/null || echo n/a)
GIT_SHA=n/a; [ "$CLONE" != "n/a" ] && GIT_SHA=$(git -C "$CLONE" rev-parse --short HEAD 2>/dev/null || echo n/a)
TEMP_DIRS=$(ls "$P/marketplaces/" 2>/dev/null | /usr/bin/grep '^temp_' | tr '\n' ' '); [ -z "$TEMP_DIRS" ] && TEMP_DIRS=none

# settings.json: extraKnownMarketplaces and enabledPlugins may be arrays or objects.
SETTINGS="$HOME/.claude/settings.json"
read -r HAS_MARKETPLACE ENABLED <<EOF
$(node -e 'try{const d=JSON.parse(require("fs").readFileSync(process.argv[1],"utf8"));const keys=x=>Array.isArray(x)?x.map(m=>typeof m==="string"?m:(m&&m.name)||""):Object.keys(x||{});const ep=d.enabledPlugins||{};const k=keys(ep).find(n=>/^commander(@|$)/i.test(n));const en=!k?"no":(!Array.isArray(ep)&&ep[k]===false?"disabled":"yes");process.stdout.write((keys(d.extraKnownMarketplaces).some(n=>/commander/i.test(n))?"yes":"no")+" "+en)}catch(e){process.stdout.write("n/a n/a")}' "$SETTINGS" 2>/dev/null)
EOF

MCP_SERVERS=$(node -e 'try{const s=JSON.parse(require("fs").readFileSync(process.argv[1],"utf8")).mcpServers||{};process.stdout.write(Object.keys(s).join(", ")||"none")}catch(e){process.stdout.write("n/a")}' "$PLUGIN_SRC/.mcp.json" 2>/dev/null)
SESSION_COUNT=$(ls "$HOME/.claude/sessions" 2>/dev/null | wc -l | tr -d ' ')
LATEST_SESSION=$(ls -t "$HOME/.claude/sessions" 2>/dev/null | head -1); [ -z "$LATEST_SESSION" ] && LATEST_SESSION=none

# Update freshness: shared update-check module, else the published manifest.
REMOTE_VERSION=n/a
if [ "$CLONE" != "n/a" ]; then REMOTE_VERSION=$(node "$CLONE/commander/update-check.js" --remote-only 2>/dev/null || echo n/a)
else REMOTE_VERSION=$(curl -fsSL --max-time 8 "https://raw.githubusercontent.com/KevinZai/commander/main/commander/cowork-plugin/.claude-plugin/plugin.json" 2>/dev/null | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{const v=JSON.parse(s).version;process.stdout.write(/^\d+\.\d+\.\d+$/.test(v)?v:"n/a")}catch(e){process.stdout.write("n/a")}})' 2>/dev/null || echo n/a); fi
CMP=$INSTALLED_VERSION; [ "$CMP" = "n/a" ] && CMP=$PLUGIN_VERSION
VERSION_STATUS="unknown — could not reach update server"
[ "$REMOTE_VERSION" != "n/a" ] && [ "$CMP" != "n/a" ] && VERSION_STATUS=$(node -e 'const [r,i]=process.argv.slice(1);const a=r.split(".").map(Number),b=i.split(".").map(Number);let gt=false;for(let n=0;n<3;n++){if((a[n]||0)>(b[n]||0)){gt=true;break}if((a[n]||0)<(b[n]||0))break}process.stdout.write(gt?"UPDATE AVAILABLE: "+i+" -> "+r:"up to date ("+i+")")' "$REMOTE_VERSION" "$CMP" 2>/dev/null || echo unknown)

# Cache dirs linger by design (no auto-clean); more than one is normal.
CACHE_ROOT="$P/cache/commander-hub/commander"
CACHE_VERSIONS=$(ls "$CACHE_ROOT" 2>/dev/null | sort -V | tr '\n' ',' | sed 's/,$//'); [ -z "$CACHE_VERSIONS" ] && CACHE_VERSIONS=none
CACHE_VERSION_COUNT=$(ls "$CACHE_ROOT" 2>/dev/null | wc -l | tr -d ' ')
INLINE_DIR="$P/data/commander-inline"; INLINE_PRESENT=no; INLINE_VERSION=n/a
[ -d "$INLINE_DIR" ] && { INLINE_PRESENT=yes; INLINE_VERSION=$(J "$INLINE_DIR/.claude-plugin/plugin.json" version); }
CATALOG_AGE_HOURS=$(node -e 'try{process.stdout.write(String(Math.floor((Date.now()-require("fs").statSync(process.argv[1]).mtimeMs)/3600000)))}catch(e){process.stdout.write("n/a")}' "$P/plugin-catalog-cache.json" 2>/dev/null)
AUTOUPDATE_FLAG=$(node -e 'try{const m=JSON.parse(require("fs").readFileSync(process.argv[1],"utf8"))["commander-hub"];process.stdout.write(m?String(!!m.autoUpdate):"not-registered")}catch(e){process.stdout.write("known_marketplaces.json not found")}' "$P/known_marketplaces.json" 2>/dev/null)

# Claude Code platform checks (absent CLI is normal for Desktop-managed installs).
CLAUDE_VER=n/a; VALIDATE=n/a; DETAILS=n/a; MOD_SUPPORT=n/a
if has claude; then
  CLAUDE_VER=$(claude --version 2>/dev/null | head -1 | awk '{print $1}')
  if [ "$PLUGIN_SRC" != "n/a" ]; then
    VALIDATE_OUT=$(claude plugin validate --strict "$PLUGIN_SRC" 2>&1); RC=$?
    [ $RC -eq 0 ] && VALIDATE=pass || VALIDATE="fail (exit $RC)"
  fi
  DETAILS=$(claude plugin details commander 2>&1 | head -40)
  MOD_SUPPORT=$(node -e 'const v=(process.argv[1]||"").split(".").map(Number);const m=[2,1,287];let ok=true;for(let i=0;i<3;i++){if((v[i]||0)>m[i])break;if((v[i]||0)<m[i]){ok=false;break}}process.stdout.write(ok?"yes":"no (needs 2.1.287+)")' "$CLAUDE_VER" 2>/dev/null)
fi
MODS_SHIPPED=$(ls "$PLUGIN_SRC/mods" 2>/dev/null | tr '\n' ' '); [ -z "$MODS_SHIPPED" ] && MODS_SHIPPED=none
MODS_INSTALLED=$(node -e 'try{const fs=require("fs");const d=JSON.parse(fs.readFileSync(process.argv[1],"utf8")).plugins||{};const out=[];for(const k of Object.keys(d)){const e=[].concat(d[k])[0];try{if(e&&/"modules"/.test(fs.readFileSync(e.installPath+"/hooks/hooks.json","utf8")))out.push(k)}catch(x){}}process.stdout.write(out.join(" ")||"none")}catch(e){process.stdout.write("n/a")}' "$INSTALLED_JSON" 2>/dev/null)

# Codex (only when installed).
CODEX_VER="not installed"; CODEX_DOCTOR=n/a; CODEX_PLUGIN=n/a
if has codex; then
  CODEX_VER=$(codex --version 2>/dev/null | head -1)
  CODEX_DOCTOR_OUT=$(codex doctor --json 2>&1); RC=$?
  [ $RC -eq 0 ] && CODEX_DOCTOR=pass || CODEX_DOCTOR="fail (exit $RC)"
  CODEX_PLUGIN=$(codex plugin list --json 2>/dev/null | /usr/bin/grep -o '"commander[^"]*"' | head -3 | tr '\n' ' '); [ -z "$CODEX_PLUGIN" ] && CODEX_PLUGIN="commander not listed"
fi

for v in INSTALL_MODE PLUGIN_SRC PLUGIN_VERSION INSTALLED_KEY INSTALLED_VERSION INSTALLED_PATH REMOTE_VERSION VERSION_STATUS \
  NODE_VER OS_INFO GIT_SHA CLONE TEMP_DIRS HAS_MARKETPLACE ENABLED MCP_SERVERS SESSION_COUNT LATEST_SESSION \
  CACHE_VERSIONS CACHE_VERSION_COUNT INLINE_PRESENT INLINE_VERSION CATALOG_AGE_HOURS AUTOUPDATE_FLAG \
  CLAUDE_VER VALIDATE MOD_SUPPORT MODS_SHIPPED MODS_INSTALLED CODEX_VER CODEX_DOCTOR CODEX_PLUGIN; do
  printf '%s=%s\n' "$v" "${!v}"
done
echo "--- validate (last 30 lines) ---"; printf '%s\n' "${VALIDATE_OUT:-n/a}" | tail -30
echo "--- plugin details ---"; printf '%s\n' "$DETAILS"
echo "--- codex doctor --json (first 3000 chars) ---"; printf '%s' "${CODEX_DOCTOR_OUT:-n/a}" | head -c 3000; echo
PROBE