# How nGPT Generates OS-Aware Shell Commands for Cross-Platform Compatibility

> Discover how nGPT generates OS-aware shell commands for cross-platform compatibility. It automatically detects your OS and shell for accurate Bash, PowerShell, and WSL command translation.

- Repository: [nazDridoy/ngpt](https://github.com/nazdridoy/ngpt)
- Tags: how-to-guide
- Published: 2026-03-07

---

**nGPT automatically detects your operating system and active shell interpreter to generate platform-specific commands, ensuring natural language requests translate correctly across Bash, PowerShell, and WSL environments.**

nGPT is an open-source CLI tool that bridges natural language and terminal commands by producing OS-aware shell commands tailored to your specific platform. Through systematic detection of operating system signals and shell environment variables in [`ngpt/cli/modes/shell.py`](https://github.com/nazdridoy/ngpt/blob/main/ngpt/cli/modes/shell.py), it eliminates manual syntax translation between Linux, macOS, Windows, and WSL systems.

## Detecting the Operating System Platform

The foundation of nGPT's cross-platform capability begins with `detect_os()` in [`ngpt/cli/modes/shell.py`](https://github.com/nazdridoy/ngpt/blob/main/ngpt/cli/modes/shell.py) (lines 48-82). This function calls Python's `platform.system()` to identify the base operating system. For Linux distributions, it executes `lsb_release -si` to obtain the specific distro name.

To handle Windows Subsystem for Linux, `detect_os()` inspects `/proc/version` for WSL signatures. When detected, it returns `Windows/WSL` as the logical operating system, allowing nGPT to treat this Linux environment as a Windows-compatible layer.

## Identifying the Active Shell Interpreter

After determining the OS, nGPT identifies the specific command interpreter through platform-specific detection methods defined in [`ngpt/cli/modes/shell.py`](https://github.com/nazdridoy/ngpt/blob/main/ngpt/cli/modes/shell.py).

### Unix-Like System Detection

On Linux, macOS (Darwin), FreeBSD, and WSL environments, `detect_unix_shell()` (lines 15-82) executes a hierarchical check:

1. **Environment variables** – Checks `BASH_VERSION`, `ZSH_VERSION`, and `FISH_VERSION` for direct shell identification
2. **Process inspection** – Reads `/proc/<pid>/cmdline` or uses `ps` to examine the parent process
3. **Process tree walking** – Traverses a short process tree to locate the originating shell
4. **Fallback check** – Examines the `$SHELL` environment variable

The first successful match wins, and the function returns a tuple containing `(shell_name, highlight_language, operating_system)`.

### Windows Environment Handling

For native Windows systems, nGPT employs two specialized detection functions:

**Git Bash Detection** – `detect_gitbash_shell()` (lines 85-112) identifies MINGW environments by checking for `MSYSTEM`, `MINGW_PREFIX`, or "mingw" entries in `PATH`. When detected, it forces the shell identification to `bash`.

**Native Windows Shells** – `detect_windows_shell()` (lines 84-130) examines `PATH`, `SHELL`, `PROMPT`, `PSModulePath`, and `ComSpec` to distinguish between:
- `cmd.exe` (Command Prompt)
- `powershell.exe` or `pwsh` (PowerShell)
- `bash` (when WSL is present)

## Integrating OS and Shell Data

The `detect_shell()` function (lines 33-69) orchestrates the platform-specific detection methods. It routes to `detect_unix_shell()` for Linux, macOS, FreeBSD, and WSL, or to the Windows detection chain for native Windows environments.

This function returns a standardized tuple of `(shell_name, highlight_language, operating_system)` that reflects both the underlying platform and the exact interpreter the user will execute commands within.

## Generating Context-Aware Commands

In `shell_mode()`, nGPT transforms detection data into LLM instructions. When no custom pre-prompt is supplied, the system formats `SHELL_SYSTEM_PROMPT` with the detected values (lines 52-55):

```python
from ngpt.cli.modes.shell import detect_shell, SHELL_SYSTEM_PROMPT

# Detect environment

shell_name, highlight_lang, operating_system = detect_shell()

# Format system prompt with OS context

system_prompt = SHELL_SYSTEM_PROMPT.format(
    shell_name=shell_name,
    operating_system=operating_system,
    prompt=user_description
)

```

This template explicitly instructs the model to output commands compatible with the detected shell and operating system. When users provide a `--preprompt` argument, `SHELL_PREPROMPT_TEMPLATE` overrides the default OS-aware instructions while preserving the detection data for syntax highlighting (lines 55-63).

## Execution and Rendering

After generation, nGPT uses the `highlight_lang` value from the detection tuple to apply correct syntax highlighting when displaying commands. The execution path specifically checks for PowerShell on Windows (`shell_name in ["powershell.exe", "pwsh"]`) to handle platform-specific invocation requirements (lines 12-20).

You can verify your detected environment using:

```python
from ngpt.cli.modes.shell import detect_shell

shell, lexer, os_name = detect_shell()
print(f"Detected shell: {shell}")
print(f"Syntax-highlight language: {lexer}")
print(f"Operating system: {os_name}")

```

*Example output on macOS Terminal:*

```text
Detected shell: zsh
Syntax-highlight language: zsh
Operating system: MacOS

```

## Summary

- **OS Detection**: `detect_os()` in [`ngpt/cli/modes/shell.py`](https://github.com/nazdridoy/ngpt/blob/main/ngpt/cli/modes/shell.py) uses `platform.system()` and `/proc/version` inspection to identify Linux, macOS, Windows, and WSL environments.
- **Shell Identification**: `detect_unix_shell()` examines environment variables and process trees on Unix systems, while `detect_gitbash_shell()` and `detect_windows_shell()` handle Windows-specific interpreters including PowerShell and Git Bash.
- **Data Integration**: The `detect_shell()` function combines OS and shell detection into a standardized tuple used throughout the application.
- **Prompt Engineering**: `SHELL_SYSTEM_PROMPT` injects platform context into LLM requests (lines 52-55), ensuring generated commands match the user's specific shell syntax and operating system capabilities.

## Frequently Asked Questions

### How does nGPT detect WSL environments?

nGPT detects WSL by reading `/proc/version` in the `detect_os()` function (lines 48-82). When this file contains WSL-specific strings, nGPT classifies the environment as `Windows/WSL` rather than standard Linux, ensuring generated commands account for Windows integration features.

### What shell detection method does nGPT use on macOS?

On macOS (Darwin), nGPT executes `detect_unix_shell()` (lines 15-82), which checks `BASH_VERSION`, `ZSH_VERSION`, and `FISH_VERSION` environment variables. If these are unset, it falls back to inspecting the parent process via `ps` or examining the `$SHELL` variable to determine whether the user runs Bash, Zsh, or Fish.

### Can nGPT handle Git Bash on Windows?

Yes. nGPT specifically identifies Git Bash and MINGW environments through `detect_gitbash_shell()` (lines 85-112) by detecting `MSYSTEM`, `MINGW_PREFIX`, or "mingw" in `PATH`. When found, it forces the shell identification to `bash` and adjusts command generation accordingly.

### Where is the core shell detection logic implemented?

All shell and OS detection logic resides in [`ngpt/cli/modes/shell.py`](https://github.com/nazdridoy/ngpt/blob/main/ngpt/cli/modes/shell.py). Key functions include `detect_os()` for platform identification, `detect_unix_shell()` for Unix-like systems, `detect_windows_shell()` for native Windows, and `detect_shell()` which orchestrates the complete detection pipeline (lines 15-130).