Peekaboo/docs/building.md

summary	read_when
How to build Peekaboo from source, run release scripts, and use the Poltergeist watcher.	compiling the CLI locally prepping release artifacts or tweaking Poltergeist workflows

Building Peekaboo

Prerequisites

• macOS 15.0+
• Swift 6.2+ toolchain (Xcode 26.x or newer recommended)
• Node.js 22+ (Corepack-enabled) — only needed for pnpm helper scripts; core Swift builds do not require Node.
• pnpm (corepack enable pnpm)

See platform-support.md for the support matrix across released binaries, apps, Swift packages, source builds, and pnpm helper scripts.

Common Builds

# Clone
git clone https://github.com/openclaw/Peekaboo.git
cd peekaboo

# Install JS deps
pnpm install

# Build everything (CLI + Swift support scripts)
pnpm run build:all

# Swift CLI only (debug)
pnpm run build:swift

# Release binary (universal)
pnpm run build:swift:all

# Standalone helper
./scripts/build-cli-standalone.sh [--install]

Releases

For full release automation (tarballs, npm package, checksums), follow RELEASING.md. Quick recap:

# Validate + prep
pnpm run prepare-release

# Generate artifacts / publish
./scripts/release-binaries.sh --create-github-release --publish-npm

Poltergeist Watcher

Peekaboo’s repo already includes poltergeist.md with tuning tips. Typical workflow:

pnpm run poltergeist:haunt   # start watcher
pnpm run poltergeist:status  # health
pnpm run poltergeist:rest    # stop

Poltergeist rebuilds the CLI whenever Swift files change so polter peekaboo … always runs a fresh binary.