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

> Learn how the Forge doctor command diagnoses shell environment issues. It checks 9 critical areas like Zsh version and dependencies returning exit code 0 only when all checks pass.

- Repository: [Forge Code/forgecode](https://github.com/antinomyhq/forgecode)
- Tags: how-to-guide
- Published: 2026-04-08

---

**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](https://github.com/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`](https://github.com/antinomyhq/forgecode/blob/main/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)](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)](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)](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`](https://github.com/antinomyhq/forgecode/blob/main/doctor.zsh) at compile time, then passes the content to `execute_zsh_script_with_streaming` ([lines 87-102](https://github.com/antinomyhq/forgecode/blob/main/crates/forge_main/src/zsh/plugin.rs#L87-L102)). 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`](https://github.com/antinomyhq/forgecode/blob/main/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:

```rust
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:

```bash

# 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`](https://github.com/antinomyhq/forgecode/blob/main/shell-plugin/doctor.zsh), implementing the logic in [`crates/forge_main/src/zsh/plugin.rs`](https://github.com/antinomyhq/forgecode/blob/main/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`](https://github.com/antinomyhq/forgecode/blob/main/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`](https://github.com/antinomyhq/forgecode/blob/main/crates/forge_main/src/zsh/plugin.rs), which loads and executes [`shell-plugin/doctor.zsh`](https://github.com/antinomyhq/forgecode/blob/main/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`](https://github.com/antinomyhq/forgecode/blob/main/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`](https://github.com/antinomyhq/forgecode/blob/main/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.