← Back to tools

poltergeist

Universal file watcher with auto-detect, hot reload, and build queuing

Homepage Repository
Development Productivity linuxmacoswindows TypeScript MIT

Description

Poltergeist is a universal file-watching and hot-reload system that automatically detects project types and rebuilds them when files change. It supports any build target (executables, app bundles, libraries, frameworks, tests, containers), provides smart build queuing, cross-platform notifications, a live status panel, and a `polter` wrapper command that waits for builds before launching binaries.

Install

homebrewbrew tap steipete/tap && brew install steipete/tap/poltergeist
npmnpm install -g @steipete/poltergeist

AI Summary

Universal file watcher and hot-reload daemon that auto-detects project types, rebuilds on file changes, and provides a `polter` wrapper to always run fresh binaries. Powered by Watchman with smart build queuing and notifications.

Capabilities

  • + Auto-detect project structure and generate build configuration (CMake, npm, Swift, etc.)
  • + Watch files for changes and trigger rebuilds automatically
  • + Smart build queuing with intelligent prioritization based on file edit history
  • + Support for any build target: executables, app bundles, libraries, frameworks, tests, containers
  • + Background daemon mode with `poltergeist haunt`
  • + Live status panel showing targets, git state, and build metrics
  • + `polter` wrapper command that waits for builds to complete before launching binaries
  • + Cross-platform native notifications with customizable sounds on build completion/failure
  • + Concurrent build protection through intelligent locking
  • + Multi-project isolation to prevent cascade failures
  • + Automatic recovery attempts after build failures
  • + Auto-reload configuration when settings change

Use When

  • → Working on a project that requires frequent rebuild-run cycles
  • → Need hot-reload for compiled languages (Swift, C++, Go, Rust)
  • → Want automatic builds triggered by file saves across any project type
  • → AI coding agents need to ensure they always run the latest build
  • → Managing multiple build targets in a polyglot workspace

Avoid When

  • x The project already has a sufficient built-in watch mode (e.g., Vite, webpack-dev-server)
  • x Working on a single-file script that does not need compilation
  • x Watchman is not available and cannot be installed

Usage Patterns

Initialize configuration

poltergeist init

Auto-detects project type and generates poltergeist.config.json

Start background watcher

poltergeist haunt

Launches the file watcher daemon in the background

Check status

poltergeist status

Shows running processes, build states, and target health

Open live dashboard

poltergeist panel

Opens a full-screen interactive status panel

Run a fresh binary

polter my-app --flags

Waits for any in-progress build to finish, then runs the binary

Manual rebuild

poltergeist build my-target

Triggers a manual rebuild of the specified target

Input / Output

stdin: Not typically used
stdout: Build output, status information, panel display
stderr: Build errors, diagnostic messages
Exit codes:
0 Success
1 Error

Typical Pipelines

poltergeist init && poltergeist haunt
poltergeist status --json | jq '.targets[].state'
polter my-app --verbose 2>&1 | tee build.log
View AGENTS.md for poltergeist