# Caveman Installation Script for Windows PowerShell: Complete Setup Guide

> Install Caveman for Windows PowerShell with our complete setup guide. This script validates Node.js and ensures a smooth, one-line installation for AI coding agents.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: how-to-guide
- Published: 2026-07-07

---

**The Caveman installation script for Windows PowerShell is a thin shim that validates Node.js ≥18 and forwards all arguments to the cross-platform Node installer at [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js), enabling one-line installation via `irm ... | iex` across all supported AI coding agents.**

Caveman is a lightweight "token-shrinker" skill designed for AI coding agents like Claude Code, Gemini CLI, and Opencode. According to the JuliusBrussee/caveman repository, the Windows entry point `install.ps1` solves cross-platform quoting issues by delegating all complex logic to a single Node.js source of truth.

## How the PowerShell Installation Script Works

### Architecture Overview

The installation architecture centers on two components working in tandem. The **`install.ps1`** file acts as a minimal wrapper that handles Windows-specific execution contexts, while **[`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js)** contains the unified installation logic used across all platforms.

When you run the PowerShell script, it first determines whether it is being executed from a pipe (`$PSCommandPath` is `$null`) or from a local clone. This detection is crucial because PowerShell's `param()` blocks cannot receive arguments when streamed via `irm ... | iex`, so the script wraps logic inside an `Install-Caveman` function to preserve the argument list (`$args`).

### Node.js Validation and Forwarding

Before delegating to the Node installer, `install.ps1` validates that **Node ≥18** is present using `Get-Command node`. If Node is missing, it prints a helpful error message with a `winget` installation command.

The script then chooses between two execution paths:

1. **Local clone**: If executed from a repository clone, it calls `node bin/install.js` directly with user-supplied flags (`& node $local @InstallerArgs`).
2. **Remote execution**: If piped from the internet, it falls back to `npx -y github:JuliusBrussee/caveman`, which downloads the pinned release (default `v1.9.1`) and runs the installer.

The underlying [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) script parses CLI flags via `parseArgs`, detects installed agents using helpers like `hasCmd` and `vscodeExtPresent`, and executes provider-specific installers such as `installClaude`, `installGemini`, or `installOpencode`.

## Installing Caveman on Windows PowerShell

### One-Line Installation (Recommended)

Run the following command in an elevated PowerShell session to install Caveman for every detected agent:

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

```

This command streams the latest `install.ps1` from the main branch, validates your Node.js installation, and automatically configures the Caveman skill across all supported AI agents found on your system.

### Per-Agent Installation

To install Caveman only for specific agents (e.g., Claude Code), append the `--only` flag:

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

```

The `--only` flag is forwarded through the PowerShell shim to [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js), which then skips the detection logic for other agents and runs only the `installClaude` routine. This copies the skill files from `skills/caveman/` into Claude's plugin directory and wires the activation hooks.

### Dry-Run Mode

Preview every file that would be copied and every command that would be executed without making changes:

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

```

This uses the Node installer's dry-run capability to show the full installation plan, including hook files from `src/hooks/` and MCP-shrink proxy registration if `--with-mcp-shrink` is specified.

## Manual Installation Fallback

If the one-liner fails due to network restrictions or quoting bugs, the repository provides a manual fallback documented in [`docs/install-windows.md`](https://github.com/JuliusBrussee/caveman/blob/main/docs/install-windows.md). This approach copies [`SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/SKILL.md) directly into the Claude Code plugin path and updates the marketplace JSON by hand.

Run these commands to manually install the core skill:

```powershell

# 1. Define paths

$ClaudeDir = if ($env:CLAUDE_CONFIG_DIR) { $env:CLAUDE_CONFIG_DIR } else { Join-Path $HOME ".claude" }
$PluginSkillDir = Join-Path $ClaudeDir ".agents\plugins\caveman\skills\caveman"
New-Item -ItemType Directory -Path $PluginSkillDir -Force | Out-Null

# 2. Copy skill definition

Copy-Item ".\skills\caveman\SKILL.md" "$PluginSkillDir\SKILL.md" -Force

# 3. Register in marketplace

$MarketplaceDir = Join-Path $ClaudeDir ".agents\plugins"
$MarketplaceFile = Join-Path $MarketplaceDir "marketplace.json"
New-Item -ItemType Directory -Path $MarketplaceDir -Force | Out-Null

$marketplace = if (Test-Path $MarketplaceFile) { 
    Get-Content $MarketplaceFile -Raw | ConvertFrom-Json 
} else { 
    [pscustomobject]@{} 
}

if (-not ($marketplace.PSObject.Properties.Name -contains "plugins")) { 
    $marketplace | Add-Member -NotePropertyName plugins -NotePropertyValue ([pscustomobject]@{}) 
}

$plugins = [ordered]@{}
foreach ($p in $marketplace.plugins.PSObject.Properties) { 
    $plugins[$p.Name] = $p.Value 
}
$plugins["caveman"] = [ordered]@{ 
    name = "caveman"; 
    source = "JuliusBrussee/caveman"; 
    version = "main" 
}
$marketplace.plugins = [pscustomobject]$plugins
$marketplace | ConvertTo-Json -Depth 10 | Set-Content -Path $MarketplaceFile -Encoding UTF8

```

Note that the manual method installs the core skill but **does not** install the standalone hooks or status-line badge. To complete the setup, run the Node installer with `--only claude` after the manual copy.

## Using Caveman After Installation

Once installed, activate the token-shrinking mode within any supported agent by typing:

```powershell
/caveman

```

Available compression levels include:

- **`/caveman lite`** – Short, aggressive trimming for quick responses
- **`/caveman full`** – Default level achieving approximately 65% token reduction
- **`/caveman ultra`** – Ultra-concise one-word replies
- **`/caveman wenyan`** – Classical Chinese-style compression that preserves meaning

The installer copies hook scripts ([`caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js), [`caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-mode-tracker.js), and `caveman-statusline.*`) from `src/hooks/` into your configuration directory. These hooks automatically switch the agent into caveman mode and display a status-line badge.

## Summary

- The **`install.ps1`** script in JuliusBrussee/caveman serves as a Windows-specific shim that forwards all flags to the unified Node.js installer at [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js).
- It validates Node.js ≥18 and handles both local execution and remote `irm ... | iex` invocation through the `Install-Caveman` function.
- The installer detects supported agents via the `PROVIDERS` matrix (lines 191-262 of [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js)) and runs appropriate routines like `installClaude` or `installOpencode`.
- Use `--only <agent>` to target specific agents and `--dry-run` to preview changes.
- If the one-liner fails, manual installation via [`docs/install-windows.md`](https://github.com/JuliusBrussee/caveman/blob/main/docs/install-windows.md) provides a fallback that copies [`SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/SKILL.md) and updates [`marketplace.json`](https://github.com/JuliusBrussee/caveman/blob/main/marketplace.json).

## Frequently Asked Questions

### What is the Caveman installation script for Windows PowerShell?

The Caveman installation script for Windows PowerShell is a thin wrapper located at `install.ps1` in the JuliusBrussee/caveman repository. It validates that Node.js is installed and then delegates all installation logic to [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js), ensuring consistent behavior across Windows, macOS, and Linux while avoiding PowerShell-specific quoting bugs that plagued earlier versions.

### How do I install Caveman only for Claude Code on Windows?

Append the `--only claude` flag to the installation command: `irm https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.ps1 | iex --only claude`. This forwards the flag through the PowerShell shim to the Node installer, which skips detection for other agents and runs only the `installClaude` routine, copying skills to the Claude plugin directory and installing activation hooks.

### Why does the PowerShell script use Node.js instead of native PowerShell commands?

Early versions used parallel Bash and PowerShell scripts that suffered from quoting bugs causing JSON merge failures on Windows (see issue #249). By centralizing all logic in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) and using `install.ps1` only for Node validation and argument forwarding, the repository guarantees identical behavior across platforms and simplifies maintenance of the provider detection matrix and installation routines.

### What should I do if the irm | iex one-liner fails on Windows?

If the one-liner fails due to execution policies or network issues, follow the manual installation steps in [`docs/install-windows.md`](https://github.com/JuliusBrussee/caveman/blob/main/docs/install-windows.md). Copy [`skills/caveman/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md) into your Claude Code plugin directory (`.claude/.agents/plugins/caveman/skills/caveman/`) and manually update [`marketplace.json`](https://github.com/JuliusBrussee/caveman/blob/main/marketplace.json) to register the plugin. Then run `npx -y github:JuliusBrussee/caveman --only claude` to install the hooks and status-line components that the manual method skips.