/environment-doctor

name: environment-doctor
description: Use when apx commands fail or assets are missing from listings, MCP servers fail to start, builds hit command-not-found or module-not-found errors, generated assets look stale, or setup works on one machine but not another.

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:

| Symptom | Likely cause | Fix | |---|---|---| | `docker: command not found` | Docker not installed | Install Docker | | `docker: not running` | Docker daemon stopped | Start Docker Desktop | | `GITHUB_TOKEN not set` | Missing env var | Set in shell profile | | Server starts then crashes | Package not cached | Run `npx -y <package>` once | | `${REPO_ROOT}` literal in args | Placeholder not replaced | Substitute actual path in config |

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.