# Cross-Platform Shell and Ollama Support

[harper-main-hq]

Cross-Platform Shell and Ollama Support

This document describes platform compatibility and implementation details for background process handling and shell execution across Linux, Windows (PowerShell), and macOS. It also clarifies where platform-specific logic exists and how the SHELL: tool behaves consistently across operating systems.

Overview

The system is designed to work across major operating systems with minimal platform-specific branching. Most commands execute uniformly, while certain components - particularly Ollama startup - require conditional handling depending on the platform.

Linux Support

Status: Fully supported

On Linux, background processes are launched using subprocess.Popen with start_new_session=True (see rag_engine.py:576):

with open(os.devnull, "w") as devnull:
    subprocess.Popen(
        [ollama_bin, "serve"],
        stdout=devnull,
        stderr=devnull,
        start_new_session=True,
    )

This approach ensures:

• Proper background execution
• No blocking of the parent process
• Clean signal isolation
• Predictable lifecycle management

Linux therefore represents the most straightforward execution path with minimal platform-specific logic.

Windows / PowerShell Support

Status: Supported

Windows requires additional handling for background process management and console separation. The implementation in rag_engine.py:561-569 includes:

if _sys.platform == "win32":
    import subprocess as sp

    creationflags = getattr(sp, "CREATE_NEW_CONSOLE", 0)
    subprocess.Popen(
        ["start", "ollama", "serve"],
        shell=True,
        creationflags=creationflags,
    )

These adjustments ensure:

• New console window creation for detached processes
• Proper background execution semantics
• Compatibility with PowerShell and CMD environments

Because Windows does not natively support POSIX-style session handling, these platform-specific flags replicate equivalent behavior.

macOS Support

Status: Supported

macOS includes explicit platform checks using sys.platform == "darwin" (see rag_engine.py:51-63):

if sys.platform == "darwin":
    os.environ.setdefault("PYTORCH_ENABLE_MPS_FALLBACK", "1")
    os.environ.setdefault("OMP_NUM_THREADS", "1")
    if torch is not None:
        try:
            torch.set_num_threads(1)
        except Exception:
            pass
    if sys.version_info >= (3, 14):
        logger.warning(
            "Python 3.14 on macOS can be unstable with torch/libomp. "
            "Use Python 3.12/3.13/3.14 or set RAG_DEVICE=cpu and OMP_NUM_THREADS=1."
        )

These checks are primarily used for:

• Apple Silicon detection
• PyTorch MPS fallback enablement
• Thread count optimization
• Python version compatibility warnings

This ensures compatibility across:

• Intel-based Macs
• Apple Silicon (M1/M2/M3) systems

The implementation maintains consistent behavior while accounting for architecture differences.

Shell Tool (SHELL:) Behavior

The SHELL: tool functions uniformly across all platforms using shell=True (see tools.py:236-248):

def _execute_shell(self, tool_call: str) -> str:
    """Execute a shell command safely."""
    command = tool_call[6:].strip()
    if not command:
        return "SHELL tool requires a command, e.g. <code>SHELL: git status</code>."
    try:
        result = subprocess.run(
            command,
            shell=True,
            capture_output=True,
            text=True,
            timeout=30,
        )
        output = result.stdout.strip() if result.stdout else ""
        if not output:
            output = result.stderr.strip() if result.stderr else ""
        if not output:
            output = "(command completed with no output)"
        return output
    except subprocess.TimeoutExpired:
        return "Command timed out after 30 seconds."
    except Exception as e:
        return f"Error executing command: {e}"

Key implementation details:

• Uses shell=True for command execution - each OS provides its own shell
• 30-second timeout prevents hanging commands
• Captures both stdout and stderr
• Works consistently across Linux, Windows, and macOS

As a result, the SHELL: tool does not require separate implementations for Linux, Windows, or macOS.

Platform-Specific Code Location

Platform-specific logic is primarily contained within two files:

rag_engine.py

Handles:

• Ollama startup behavior (line 561-577 in rag_engine.py)
• Ollama stop behavior with platform-specific pkill (line 591-594 in rag_engine.py)
• macOS-specific PyTorch and thread configuration (line 51-63 in rag_engine.py)
• OS detection for process management

config.py

Handles device selection with platform detection (line 17 in config.py):

default_device = "cpu" if sys.platform == "darwin" else "cpu"

Currently both evaluate to "cpu", but this allows future platform-specific device selection (e.g., GPU on Linux, MPS on macOS).

Keeping platform-specific code centralized simplifies maintenance and improves clarity.

Summary

Platform	Support Level	Notes
Linux	Fully supported	Uses subprocess.Popen with start_new_session=True
Windows / PowerShell	Supported	Uses start command and CREATE_NEW_CONSOLE
macOS	Supported	Uses sys.platform == "darwin" and Apple Silicon checks

The SHELL: tool works consistently across all platforms, while platform-specific logic is mainly confined to rag_engine.py for Ollama startup handling.

---

This document was verified against the codebase on 2026-04-03. All code references and line numbers are based on actual source files.

Originally posted by @bniladridas in #78