How the Forge Doctor Command Diagnoses Shell Environment Issues: A Complete Technical Guide

The forge doctor command streams a comprehensive Zsh diagnostic script that checks nine critical environment areas—including shell version, dependency binaries, keyboard configuration, and Nerd Font support—returning exit code 0 only when all checks pass.

The forge doctor command in the antinomyhq/forgecode repository serves as the primary entry point for validating your terminal setup. Rather than implementing diagnostic logic directly in Rust, the command acts as a robust wrapper around a curated Zsh script, ensuring accurate detection of shell-specific configurations and real-time feedback.

Architecture of the Forge Doctor Command

The command delegates all diagnostic logic to shell-plugin/doctor.zsh, while the Rust codebase handles process spawning and output streaming. This architecture ensures consistent behavior across Unix and Windows platforms while maintaining the flexibility of native Zsh environment inspection.

UI Handler and Entry Points

When you execute forge doctor, the CLI routes through on_zsh_doctor defined in [crates/forge_main/src/ui.rs](https://github.com/antinomyhq/forgecode/blob/main/crates/forge_main/src/ui.rs#L48-L56). This handler stops any active spinner and immediately invokes crate::zsh::run_zsh_doctor(). The command is also aliased in [crates/forge_main/src/cli.rs](https://github.com/antinomyhq/forgecode/blob/main/crates/forge_main/src/cli.rs#L149-L154), meaning forge doctor and forge zsh doctor execute identical code paths.

Zsh Script Execution Layer

The core execution logic resides in [crates/forge_main/src/zsh/plugin.rs](https://github.com/antinomyhq/forgecode/blob/main/crates/forge_main/src/zsh/plugin.rs#L75-L83) inside the run_zsh_doctor function. This function uses include_str! to embed doctor.zsh at compile time, then passes the content to execute_zsh_script_with_streaming (lines 87-102). This helper method spawns a Zsh subprocess—using zsh -c on Unix or a temporary file with zsh -f on Windows—and streams stdout and stderr line-by-line to preserve the script's colorized output.

The Nine Diagnostic Checks Performed by Forge Doctor

The doctor.zsh script performs nine distinct validation categories, outputting PASS, WARN, or FAIL status for each item before providing a final summary count.

1. Shell Environment Validation

The script verifies your Zsh version is ≥ 5.0, detects the active terminal program via TERM_PROGRAM and TERM variables, and checks for Oh My Zsh presence and version. This ensures the underlying shell meets minimum requirements for Forge plugins.

2. Forge Installation Status

This check confirms the forge binary exists in your $PATH and extracts the exact version string using forge --version. A typical output reads forge: 33.0.0.

3. Plugin Loading Verification

The script inspects the _FORGE_PLUGIN_LOADED environment variable to confirm the Forge Zsh plugin is active. It also validates load order, ensuring the plugin executes after any plugins=(…) declarations in your ~/.zshrc. If missing, it provides the exact eval "$(forge zsh plugin)" instruction needed.

4. Right Prompt (RPROMPT) Theme Detection

Checking the _FORGE_THEME_LOADED flag, this section validates the Forge theme is active in your right prompt. It specifically detects competing themes like Powerlevel10k and warns if the Forge theme is absent, suggesting eval "$(forge zsh theme)" to resolve.

5. Required Binary Dependencies

The doctor strictly enforces minimum versions for three critical tools:

• fzf ≥ 0.36.0
• fd or fdfind ≥ 10.0.0
• bat ≥ 0.20.0 (required for syntax-highlighted previews)

Failures include direct installation URLs.

6. Essential Zsh Plugins

This check confirms zsh-autosuggestions and zsh-syntax-highlighting are loaded in the current shell. If either is missing, the script outputs WARN status with specific install instructions.

7. System Configuration

The script validates that FORGE_EDITOR or EDITOR is set, and verifies standard $PATH directories (/usr/local/bin, /usr/bin) are present. Missing configurations trigger WARN with contextual hints.

8. Keyboard Configuration

Platform-specific meta-key settings are verified:

• macOS: Checks VS Code, iTerm2, and Terminal.app for Option-as-Meta configuration
• Linux: Validates VS Code, GNOME Terminal, Konsole, Alacritty, and xterm for Alt-as-Meta support

When misconfigured, the script provides concrete "add to settings" snippets.

9. Nerd Font Support

The script detects NERD_FONT or USE_NERD_FONT environment variables. If enabled, it displays a visual sanity check of icons to verify glyph rendering.

Real-Time Streaming Implementation

The execute_zsh_script_with_streaming function ensures diagnostic output appears immediately rather than buffering until completion. The implementation uses scoped threads to parallelize stdout and stderr processing:

fn execute_zsh_script_with_streaming(script_content: &str, script_name: &str) -> Result<()> {
    let script_content = super::normalize_script(script_content);

    let (_temp_dir, mut child) = if cfg!(windows) {
        std::process::Command::new("zsh")
            .arg("-f")
            .arg(script_path)
            .stdout(Stdio::piped())
            .stderr(Stdio::piped())
            .spawn()?
    } else {
        std::process::Command::new("zsh")
            .arg("-c")
            .arg(&script_content)
            .stdout(Stdio::piped())
            .stderr(Stdio::piped())
            .spawn()?
    };

    std::thread::scope(|s| {
        s.spawn(|| {
            let reader = BufReader::new(child.stdout.take().unwrap());
            for line in reader.lines() { println!("{}", line.unwrap()); }
        });
        s.spawn(|| {
            let reader = BufReader::new(child.stderr.take().unwrap());
            for line in reader.lines() { eprintln!("{}", line.unwrap()); }
        });
    });

    let status = child.wait()?;
    if !status.success() {
        anyhow::bail!("ZSH {} script failed with exit code: {:?}", script_name, status.code());
    }
    Ok(())
}

The -f flag prevents ~/.zshrc from being sourced on Windows, guaranteeing a deterministic diagnostic environment. The function returns an error if the script exits with a non-zero status code.

Running the Forge Doctor Command

Invoke diagnostics directly from your terminal:

# Standard execution (alias for forge zsh doctor)

$ forge doctor

# Explicit subcommand variant

$ forge zsh doctor

# View the Zsh plugin source without executing diagnostics

$ forge zsh plugin

# Test keyboard shortcuts after diagnosis

$ forge zsh keyboard

All commands stream output in real-time, maintaining color codes from the underlying Zsh script.

Summary

• The Forge doctor command wraps a Zsh diagnostic script located at shell-plugin/doctor.zsh, implementing the logic in crates/forge_main/src/zsh/plugin.rs.
• It performs nine categories of checks: shell environment, Forge installation, plugin loading, RPROMPT theme, dependencies (fzf, fd, bat), Zsh plugins (autosuggestions, syntax-highlighting), system configuration, keyboard meta-keys, and Nerd Font support.
• The Rust layer handles real-time streaming via execute_zsh_script_with_streaming, using scoped threads to pipe stdout/stderr line-by-line.
• On Windows, the script executes with zsh -f to avoid sourcing user configuration; on Unix, it uses zsh -c.
• Exit code 0 indicates a clean environment; 1 indicates one or more failures.

Frequently Asked Questions

What is the difference between forge doctor and forge zsh doctor?

There is no functional difference. According to the source in crates/forge_main/src/cli.rs (lines 149-154), doctor is defined as an alias for the zsh doctor subcommand. Both invoke run_zsh_doctor() in crates/forge_main/src/zsh/plugin.rs, which loads and executes shell-plugin/doctor.zsh.

Why does Forge implement diagnostics as a Zsh script rather than native Rust code?

The diagnostic logic requires inspection of Zsh-specific state—including variables like _FORGE_PLUGIN_LOADED, the RPROMPT configuration, and ~/.zshrc load order—that is only accessible from within a running Zsh shell. By embedding the script with include_str! and spawning a Zsh subprocess, Forge gains accurate environment detection while maintaining Rust's cross-platform process management.

How does the doctor command handle output streaming on different operating systems?

The execute_zsh_script_with_streaming function in crates/forge_main/src/zsh/plugin.rs (lines 87-102) adapts to the platform: on Unix, it passes the script content directly via zsh -c; on Windows, it writes the script to a temporary file and executes with zsh -f <file>. In both cases, it spawns scoped threads to read stdout and stderr line-by-line, ensuring real-time colorized output without buffering.

What exit codes does forge doctor return?

The command returns exit code 0 only when the doctor.zsh script reports all checks passed (e.g., "All checks passed (33)"). If any failures occur, the Rust wrapper converts the non-zero Zsh exit status into a Rust error, resulting in exit code 1. Warnings alone do not trigger a failure unless accompanied by explicit FAIL states.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}