Installation

npm is the primary install path. Native binaries via Homebrew / Docker / direct download are also available.

npm

Canonical (npm)

Requires Node.js 20+:

# npm
npm install -g @juliusbrussee/caveman-code

# bun
bun add -g @juliusbrussee/caveman-code

# yarn
yarn global add @juliusbrussee/caveman-code

# pnpm
pnpm add -g @juliusbrussee/caveman-code

The package installs two binaries — caveman (primary) and caveman-code (alias). Either works.

caveman --version
caveman

Works on macOS, Linux, Windows (PowerShell + WSL). Same package on every platform.

Homebrew

brew tap juliusbrussee/caveman-code https://github.com/JuliusBrussee/caveman-cli
brew install caveman-code

The tap is auto-updated by the release pipeline.

Docker

docker run --rm -it -v "$PWD:/work" ghcr.io/juliusbrussee/caveman-cli:latest

Mounts your working directory into /work. The image runs as a non-root user.

Windows

npm install -g @juliusbrussee/caveman-code

The npm package works on Windows PowerShell and WSL. WSL is the supported terminal path.

Manual

Grab the platform-specific tarball from the GitHub releases page and extract to a directory on your PATH.

Verify

caveman --version
caveman doctor

caveman doctor reports:

• Kernel and terminal capabilities
• Sandbox availability (Seatbelt / Landlock / Restricted Tokens)
• MCP servers reachable
• Missing tooling (git, ripgrep, fzf — used optionally for fuzzy file pickers)

Auto-update

Caveman Code checks the GitHub releases API once per 24 hours and prompts before applying.

1. Pin a channel (optional):

caveman update --channel stable    # default
caveman update --channel beta
caveman update --channel canary

2. Update on demand:

caveman update

To roll back to the previous version:

caveman update --rollback

Headless / CI install

npm install -g @juliusbrussee/caveman-code@0.65.2   # pin a version for reproducible CI

See caveman exec mode for using caveman inside GitHub Actions.