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

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, 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 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, 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 and caveman-statusline.ps1 in the src/hooks/ directory. The activation logic in 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, which utilizes path.win32 for Windows-specific path operations. This ensures backslashes in 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, 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):

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

Windows PowerShell 5.1+:

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:

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

# 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 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) 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 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 and 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 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, 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. When merging or reading settings.json, the code ensures backslashes are correctly interpreted on Windows while maintaining compatibility with forward-slash conventions used on macOS and Linux systems.

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