---
name: ai-tools-doctor
description: Check and sync AI coding tool versions against declared manifest
---

# AI Tools Doctor

Check installed AI tools against declared versions and sync npm tools to pinned versions.

## When to Use

- At session start to verify tool versions
- When user asks about AI tool status or versions
- Before/after updating tools
- When troubleshooting tool issues

## Commands

```bash
# Check all tools (human-readable)
ai-tools-doctor check

# Check all tools (machine-readable for parsing)
ai-tools-doctor check --json

# Exit code only (for scripts/hooks)
ai-tools-doctor check --quiet

# Sync npm tools to declared versions
ai-tools-doctor sync
```

## Managed Tools

| Tool | Source | Binary |
|------|--------|--------|
| claude-code | npm | `claude` |
| openai-codex | npm | `codex` |
| opencode | nix | `opencode` |
| beads | nix | `bd` |

## Output

### Human-readable (default)
```
beads (nix)
  ✓ 0.26.0
claude-code (npm)
  ✓ 2.0.55
```

### JSON (--json)
```json
{
  "status": "ok",
  "tools": {
    "claude-code": {
      "source": "npm",
      "installed": "2.0.55",
      "declared": "2.0.55",
      "status": "ok"
    }
  }
}
```

## Status Values

- `ok` - Installed version matches declared
- `version_mismatch` - Installed differs from declared
- `not_installed` - Tool not found

## Exit Codes

- `0` - All tools match declared versions
- `1` - Mismatch or error

## Notes

- Nix tools are read-only (reports status, doesn't manage)
- Use `sync` to install/update npm tools to declared versions
- Manifest location: `~/.config/ai-tools/tools.json`
