Environment Doctor

Environment Doctor

Systematically diagnose why the agent environment, project tooling, or Agent Powerups installation is not working as expected.

When to Use

• apx commands fail with unexpected errors or "not found"
• MCP servers fail to start or respond
• Skills or commands are missing from apx list
• Build or test commands fail with "command not found" or "module not found"
• Generated assets appear stale (catalog, README, types)
• Setup works on one machine but not another
• After a fresh clone or environment reset

Inputs

• Platform: Claude Code, Codex, Gemini CLI, or generic shell
• Agent root path (if APX_REPO_ROOT is set, note its value)
• The exact error or symptom observed
• Output of any failing command

Workflow

1. Check required commands

Run each and note missing or wrong-version ones:

node --version        # 18+ for most Agent Powerups tooling
npx --version
python --version      # 3.9+ for validate scripts
git --version
apx --version         # Agent Powerups CLI
docker --version      # only if using Docker-based MCP configs

2. Verify Agent Powerups installation

apx list
apx validate skills
apx validate catalog

If apx is not found:

• Check global npm packages: npm list -g agent-powerups
• Check PATH: echo $PATH (bash/zsh) or $env:PATH (PowerShell)
• Reinstall or re-add to PATH per docs/installation.md

3. Check MCP configs

For each MCP config that should be active:

apx mcp check <name>   # prerequisites: required commands, env vars
apx mcp smoke <name>   # launch test: does the server actually start?

Common failures:

4. Validate catalog and skills

python scripts/validate-catalog.py
python scripts/validate-skills.py

Each error line names the asset and the exact failing field. Fix in order.

5. Check for stale generated assets

git status --short
git diff --stat

Stale generated files will show as modified. Re-run the generator script to bring them current.

6. Check environment variables

List what is expected versus what is set — show presence, not values:

# bash/zsh
printenv | grep -E "GITHUB|CONTEXT7|OPENAI|ANTHROPIC" | sed 's/=.*/=SET/'

# PowerShell
Get-ChildItem Env: | Where-Object { $_.Name -match "GITHUB|CONTEXT7" } | Select-Object Name

7. Check paths

ls <agent-root>/skills/
ls <agent-root>/commands/
ls <agent-root>/mcp/

If paths are empty or missing: verify APX_REPO_ROOT or the install path passed to apx.

Output

ENVIRONMENT DOCTOR REPORT

Platform: <claude-code / codex / gemini-cli / generic>
Agent root: <path or "not set">

REQUIRED COMMANDS:
  node: 20.x ✓ / MISSING ✗
  npx: ✓ / MISSING
  python: 3.11 ✓ / MISSING
  git: ✓ / MISSING
  apx: 0.x ✓ / MISSING

MCP CONFIGS:
  <name>: check OK / FAIL — <reason>
  <name>: smoke OK / FAIL — <reason>

ASSET VALIDATION:
  catalog: PASS / FAIL — [N errors]
  skills:  PASS / FAIL — [N errors]

STALE GENERATED ASSETS: none / [list]

MISSING ENV VARS: none / [list of names only, no values]

BLOCKERS (must fix before proceeding):
  - [item]

NON-BLOCKING:
  - [item]

Verification

• All required commands found at expected versions
• apx validate catalog and apx validate skills exit 0
• All active MCP configs pass check and smoke
• No required env vars missing

Failure Modes

• apx not in PATH after install — reload shell profile (source ~/.zshrc) or restart terminal
• Docker daemon not running for Docker-based MCP — start Docker Desktop before smoke
• ${REPO_ROOT} literal in filesystem MCP args — substitute the actual absolute path
• APX_REPO_ROOT pointing to a stale path after a repo move — update the env var

Sources / Inspiration

Inspired by Yeachan-Heo/oh-my-codex skills/doctor/SKILL.md. Rewritten in Agent Powerups style with multi-platform coverage for Claude Code, Codex, Gemini CLI, and generic shell environments.