Caveman Installation Script for Windows PowerShell: Complete Setup Guide

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

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:

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

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. This approach copies 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:

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

/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, 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.
• 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) 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 provides a fallback that copies SKILL.md and updates 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, 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 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. Copy skills/caveman/SKILL.md into your Claude Code plugin directory (.claude/.agents/plugins/caveman/skills/caveman/) and manually update 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.

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