Doctor All Tiers

Overview

bpsai-pair doctor validates your development environment by running nine health checks against required and optional dependencies. Each check reports a color-coded status, and the optional --fix flag can auto-repair common issues.

# Run all checks
bpsai-pair doctor

# Auto-fix what can be repaired
bpsai-pair doctor --fix

# Machine-readable output
bpsai-pair doctor --json

The command exits with code 0 if all checks pass (green or yellow) and code 1 if any check fails (red). This makes it suitable for CI pipelines and setup scripts.

Status Colors

Each check reports one of three statuses:

Yellow warnings do not cause a non-zero exit. Only red failures block.

Checks Performed

Doctor runs nine checks in order. The first four are critical requirements (red on failure). The next two validate project directories. The last three check optional tooling.

1. Python Version

Validates that Python 3.9 or higher is installed.

Fix hint: Install Python 3.9+ from python.org.

2. PairCoder Version

Reports the installed bpsai-pair package version.

3. Claude Code CLI

Checks whether the claude CLI is installed and accessible on PATH.

Fix hint: Install Claude Code from claude.ai/code.

4. Git Repository

Validates that a .git/ directory exists in the project root.

Fix hint: Run git init to initialize a repository.

5. .paircoder/ Directory

Checks for the .paircoder/ directory and its expected contents: config.yaml, capabilities.yaml, and the context/ subdirectory.

Fix hint: Run bpsai-pair init to scaffold the directory.

6. .claude/ Directory

Checks for the .claude/ directory and its expected subdirectories: agents/, skills/, and commands/.

Fix hint: Run bpsai-pair init to scaffold the directory.

7. Ruff Linter

Checks whether ruff is installed. Ruff is optional but recommended for Python linting.

Fix hint: Run pip install ruff.

8. pytest

Checks whether pytest is installed. pytest is optional but recommended for running tests.

Fix hint: Run pip install pytest.

9. Telemetry Directory

Checks whether .paircoder/telemetry/ exists and is writable. This directory is created on first use and stores local telemetry data.

Fix hint: Run mkdir -p .paircoder/telemetry.

Auto-Fix

The --fix flag attempts to repair fixable checks automatically. After each fix attempt, the check is re-run to verify success.

bpsai-pair doctor --fix

The --fix flag is idempotent. Running it multiple times has no additional effect once all fixable issues are resolved.

JSON Output

The --json flag outputs structured JSON instead of the formatted table. Use this for scripting and CI pipelines.

bpsai-pair doctor --json

{
  "checks": [
    { "name": "python_version", "status": "green", "detail": "3.12.0" },
    { "name": "paircoder_version", "status": "green", "detail": "2.23.0" },
    { "name": "claude_code", "status": "green", "detail": "1.0.12" },
    { "name": "git", "status": "green", "detail": ".git/ found" },
    { "name": "paircoder_dir", "status": "green", "detail": "complete" },
    { "name": "claude_dir", "status": "green", "detail": "complete" },
    { "name": "ruff", "status": "green", "detail": "0.5.0" },
    { "name": "pytest", "status": "green", "detail": "8.2.0" },
    { "name": "telemetry_dir", "status": "green", "detail": "writable" }
  ],
  "summary": { "green": 9, "yellow": 0, "red": 0 }
}

When any check is red, the JSON wrapper uses the error envelope and the command exits with code 1.

Common Issues

Fresh Clone With No .paircoder/ Directory

After cloning a new repository, run bpsai-pair init to scaffold the project. Alternatively, run bpsai-pair doctor --fix to create the minimum directory structure.

# Full init (recommended)
bpsai-pair init

# Or quick fix for directories only
bpsai-pair doctor --fix

Claude Code Not Found

If the Claude Code check fails, ensure the claude binary is on your PATH. Common causes:

• Claude Code was installed but the terminal was not restarted
• The install location is not on PATH (check ~/.local/bin or /usr/local/bin)
• Using a restricted shell or container that does not have Claude Code installed

Python Version Too Old

PairCoder requires Python 3.9 or higher. If your system Python is older, consider using pyenv to manage multiple Python versions.

# Install a compatible Python version
pyenv install 3.12.0
pyenv local 3.12.0

Partial .paircoder/ or .claude/ Setup

If the directory exists but expected files or subdirectories are missing, the check reports yellow. Run bpsai-pair doctor --fix to create missing subdirectories, or bpsai-pair init for a complete scaffold including config files.

Telemetry Directory Missing

The telemetry directory is created automatically on first use. A yellow warning here is normal for new projects. Run bpsai-pair doctor --fix or any command that emits telemetry to create it.

Examples

# Check environment health
bpsai-pair doctor

# Auto-fix and verify
bpsai-pair doctor --fix

# JSON output for CI
bpsai-pair doctor --json

# Combine flags
bpsai-pair doctor --fix --json

# Use in a setup script
bpsai-pair doctor --fix || echo "Some checks still failing"

# Gate a CI step on environment health
bpsai-pair doctor --json || exit 1