# Is Caveman Cross-Platform Compatible? macOS, Linux, and Windows Support Explained

> Is caveman cross-platform compatible? Discover how Caveman supports macOS, Linux, and Windows with its unified Node.js installer for seamless development across all major operating systems.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: getting-started
- Published: 2026-07-04

---

**Caveman is fully cross-platform compatible with macOS, Linux (including WSL), and Windows, using a unified Node.js installer that automatically detects the host OS and deploys the appropriate shell hooks.**

The Caveman project by JuliusBrussee is an AI-coding agent enhancement tool designed to work seamlessly across every major desktop platform. Unlike platform-specific tools requiring separate codebases, Caveman employs a single Node.js installer that handles macOS, Linux distributions, and Windows environments—including WSL and PowerShell—without modification.

## How Caveman Achieves Cross-Platform Compatibility

### Unified Installer Architecture

The backbone of Caveman's portability lies in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js), which serves as the single entry point for all platforms. This script detects the host operating system using `process.platform` and automatically selects the correct hook files—`*.sh` for Unix-like shells and `*.ps1` for PowerShell. According to the source code, the installer copies both sets of hooks regardless of the current platform, ensuring users can migrate their configuration directories between machines without losing functionality.

### Platform-Specific Shim Scripts

Rather than duplicating complex OS logic, Caveman uses thin wrapper scripts that delegate to the unified installer. The [`install.sh`](https://github.com/JuliusBrussee/caveman/blob/main/install.sh) script for Unix systems and `install.ps1` for Windows PowerShell merely bootstrap the Node installer. This architecture keeps platform-specific code minimal—each shim passes control to [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js), which handles the heavy lifting of file placement and configuration.

### Dual Hook Script Strategy

Caveman maintains parallel hook implementations for maximum compatibility. The repository includes both [`caveman-statusline.sh`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-statusline.sh) and `caveman-statusline.ps1` in the `src/hooks/` directory. The activation logic in [`src/hooks/caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-activate.js) specifically checks `process.platform === 'win32'` to determine which script extension to use. This ensures that whether you're running Bash on Ubuntu or PowerShell on Windows 11, the status line integration works identically.

### Windows Path Handling and WSL Detection

Cross-platform path handling is implemented in [`bin/lib/settings.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/lib/settings.js), which utilizes `path.win32` for Windows-specific path operations. This ensures backslashes in [`settings.json`](https://github.com/JuliusBrussee/caveman/blob/main/settings.json) are correctly interpreted on Windows while remaining compatible with forward-slash conventions on Unix systems. Additionally, the installer includes `checkWslWindowsNode()` in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js), which detects when a Windows Node.js binary runs inside WSL and prompts users to switch to a native Linux Node installation, preventing home directory misconfiguration.

## Installing Caveman on Different Operating Systems

You can deploy Caveman using one-line commands tailored to your shell environment, or run the Node installer directly for advanced options.

**macOS, Linux, and WSL (Bash/Zsh):**

```bash
curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash

```

**Windows PowerShell 5.1+:**

```powershell
irm https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.ps1 | iex

```

**Direct Node Installation (All Platforms):**

For debugging, custom agent selection, or dry-run verification, invoke the unified installer directly:

```bash

# Install for all detected agents

node bin/install.js --all

# Install only for Claude Code

node bin/install.js --only claude

# Preview changes without modifying files

node bin/install.js --dry-run

```

After installation, verify the correct platform-specific hooks were deployed:

```bash

# Unix-like systems

cat "${HOME}/.claude/hooks/caveman-statusline.sh"

# Windows PowerShell

type "$env:APPDATA\Claude\hooks\caveman-statusline.ps1"

```

## Node.js Version Requirements

Caveman requires Node.js version 18 or higher, a cross-platform runtime that ensures consistent behavior. The `checkNodeVersion()` function in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) aborts the installation early if it detects an unsupported version, preventing runtime errors across different operating systems.

## Summary

- **Single Codebase**: Caveman uses one Node.js installer ([`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js)) for macOS, Linux, and Windows, eliminating platform-specific forks.
- **Automatic OS Detection**: The installer detects `process.platform` to select appropriate `.sh` or `.ps1` hook scripts.
- **Windows Compatibility**: Dedicated PowerShell hooks and `path.win32` handling in [`bin/lib/settings.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/lib/settings.js) ensure native Windows support alongside Unix systems.
- **WSL Support**: Built-in detection via `checkWslWindowsNode()` prevents configuration errors when running Windows Node binaries inside WSL.
- **Universal Documentation**: The [`README.md`](https://github.com/JuliusBrussee/caveman/blob/main/README.md) and [`INSTALL.md`](https://github.com/JuliusBrussee/caveman/blob/main/INSTALL.md) explicitly declare support for macOS, Linux, WSL, Git Bash, and PowerShell 5.1+.

## Frequently Asked Questions

### Does Caveman work on Windows PowerShell 5.1?

Yes. Caveman explicitly supports Windows PowerShell 5.1 and newer through dedicated `install.ps1` and `caveman-statusline.ps1` scripts. The PowerShell installation shim downloads and executes the unified Node installer, which then deploys platform-specific hooks to your Claude configuration directory.

### Can I use Caveman with WSL (Windows Subsystem for Linux)?

Yes. Caveman fully supports WSL, though the installer includes a safety check via `checkWslWindowsNode()` in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) to detect if you're running a Windows Node.js binary inside WSL. If detected, it prompts you to install the Linux-native Node.js version to prevent path resolution issues with your home directory.

### What Node.js version is required for Caveman?

Caveman requires Node.js version 18 or higher. This requirement is enforced cross-platform by the `checkNodeVersion()` function in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js), which terminates the installation process before any file system modifications if it detects an older Node version.

### How does Caveman handle path separators on Windows?

Caveman handles Windows path separators through `path.win32` operations in [`bin/lib/settings.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/lib/settings.js). When merging or reading [`settings.json`](https://github.com/JuliusBrussee/caveman/blob/main/settings.json), the code ensures backslashes are correctly interpreted on Windows while maintaining compatibility with forward-slash conventions used on macOS and Linux systems.