doctor Command

The doctor command provides a diagnostic tool for checking the health of the Claude Code installation, with a focus on npm permissions required for proper auto-updating functionality.

Implementation

The command is implemented in commands/doctor.ts as a type: 'local-jsx' command that renders a React component:

import React from "react";
import type { Command } from "../commands";
import { Doctor } from "../screens/Doctor";

const doctor: Command = {
  name: "doctor",
  description: "Checks the health of your Claude Code installation",
  isEnabled: true,
  isHidden: false,
  userFacingName() {
    return "doctor";
  },
  type: "local-jsx",
  call(onDone) {
    const element = React.createElement(Doctor, {
      onDone,
      doctorMode: true,
    });
    return Promise.resolve(element);
  },
};

export default doctor;

The command uses the Doctor screen component defined in screens/Doctor.tsx, passing the special doctorMode flag to indicate it's being used as a diagnostic tool rather than during initialization.

Functionality

The doctor command implements a comprehensive installation health check focused on npm permissions:

  1. Permissions Verification:

    • Checks if the npm global installation directory has correct write permissions
    • Determines the current npm prefix path
    • Validates if auto-updates can function correctly

  2. Status Reporting:

    • Provides clear success or failure messages about installation health
    • Shows a green checkmark and confirmation message for healthy installations
    • Presents an interactive dialog for resolving permission issues

  3. Problem Resolution:

    • Offers three remediation options when permission problems are detected:
      1. Manual Fix: Provides a sudo/icacls command to fix permissions on the current npm prefix
      2. New Prefix: Guides the user through creating a new npm prefix in their home directory
      3. Skip: Allows deferring the fix until later

  4. Installation Repair:

    • For the "new prefix" option, provides a guided, step-by-step process to:
      • Create a new directory for npm global packages
      • Configure npm to use the new location
      • Update shell PATH configurations
      • Reinstall Claude Code globally

Technical Implementation Notes

The command demonstrates several sophisticated implementation patterns:

  1. Component-Based Architecture: Uses React components for the UI, allowing for a rich interactive experience.

  2. Platform-Aware Logic: Implements different permission-fixing approaches for Windows vs. Unix-like systems:

    • Windows: Uses icacls for permission management and setx for PATH updates
    • Unix: Uses sudo chown/chmod for permission fixes and shell config file updates

  3. Shell Detection: For Unix platforms, identifies and updates multiple possible shell configuration files:

    • .bashrc and .bash_profile for Bash
    • .zshrc for Zsh
    • config.fish for Fish shell

  4. Status Management: Uses React state to track:

    • Permission check status
    • Selected remediation option
    • Custom prefix path (if chosen)
    • Step-by-step installation progress

  5. Lock-Based Concurrency Control: Implements a file-based locking mechanism to prevent multiple processes from attempting auto-updates simultaneously.

  6. Error Handling: Provides detailed error reporting and recovery options:

    • Shows precisely which operation failed
    • Offers alternative approaches when errors occur
    • Logs error details for debugging

User Experience Benefits

The doctor command addresses several important pain points for CLI tool users:

  1. Installation Troubleshooting: Provides clear diagnostics and fixes for common problems:

    • Permission issues that prevent updates
    • Global npm configuration problems
    • PATH configuration issues

  2. Security-Conscious Design: Offers both privileged (sudo) and non-privileged (new prefix) solutions, allowing users to choose based on their security preferences.

  3. Multi-Platform Support: Works identically across Windows, macOS, and Linux with platform-appropriate solutions.

  4. Shell Environment Enhancement: Automatically updates shell configuration files to ensure the installation works correctly across terminal sessions.

  5. Visual Progress Feedback: Uses spinners and checkmarks to keep users informed about long-running operations.

The command provides a comprehensive diagnostics and repair tool that helps maintain a healthy Claude Code installation, particularly focusing on the auto-update capability which is crucial for keeping the tool current with new features and improvements.