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

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, 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 (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.

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):

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:

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:

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

Summary

• OS Detection: detect_os() in 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. 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).

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