Poltergeist

The ghost that keeps your builds fresh 👻
A universal file watcher with auto-rebuild for any language or build system

Poltergeist is an AI-friendly universal file-watcher that auto-detects any project and rebuilds them as soon as a file has been changed. Think npm run dev for native apps, with automatic configuration, notifications and a smart build queue. It stands on the shoulders of giants and fills the glue layer that's been missing.

Works on macOS, Linux, and Windows. Available as a standalone binary (no Node.js required) or npm package.

📖 Read the story behind Poltergeist: The Ghost That Keeps Your Builds Fresh - Learn how this tool was built using Claude Code and why it's designed to accelerate both human and AI development workflows.

brew tap steipete/tap
brew install poltergeist

npm install -g @steipete/poltergeist

Poltergeist requires Watchman to be installed:

• macOS: brew install watchman
• Linux: Installation guide
• Windows: Chocolatey package or manual install

Poltergeist offers both a CLI tool for universal development and a native macOS app for enhanced monitoring (coming soon).

• Universal Target System: Support for anything you can build - executables, app bundles, libraries, frameworks, tests, Docker containers, ...
• Smart Execution Wrapper: polter command that waits for a build to complete, then starts it
• Real-time Build Output: See build progress as it happens, no more waiting in the dark
• Inline Error Diagnostics: Build errors shown immediately with context and actionable suggestions
• Manual Build Command: Trigger builds explicitly with poltergeist build [target]
• Automatic Recovery: Recent build failures trigger automatic rebuild attempts
• Efficient File Watching: Powered by Facebook's Watchman with smart exclusions and performance optimization
• Intelligent Build Prioritization: Having multiple projects that share code? Polgergeist will compile the right one first, based on which files you edited in the past
• Automatic Project Configuration: Just type poltergeist init and it'll parse your folder and set up the config.
• Native Notifications: System notifications with customizable sounds and icon for build status
• Concurrent Build Protection: Intelligent locking prevents overlapping builds
• Advanced State Management: Process tracking, build history, and heartbeat monitoring
• Automatic Configuration Reloading: Changes to poltergeist.config.json are detected and applied without manual restart

Install globally via npm:

npm install -g @steipete/poltergeist

1. Automatic Configuration - Let Poltergeist analyze your project:

poltergeist init

This automatically detects your project type (Swift, Node.js, Rust, Python, CMake, etc.) and creates an optimized configuration.

2. Start Watching - Begin auto-building on file changes:

poltergeist haunt             # Runs as background daemon (default)
poltergeist status            # Check what's running
poltergeist status --verbose  # Show detailed status with build stats

3. Execute Fresh Builds - Use polter to ensure you never run stale code:

polter my-app            # Waits for build, then runs fresh binary
polter my-app --help     # All arguments passed through

That's it! Poltergeist now watches your files and rebuilds automatically.

Each project gets its own background process, but poltergeist status shows everything through a shared state system in /tmp/poltergeist/. One project crashing never affects others.

Poltergeist can power hot-reload loops for native apps, backends, and hybrid workspaces. The daemon handles rebuilds while polter relaunches binaries only after they are fresh.

1. Auto-detect your build targets

   poltergeist init --auto

   Review the generated poltergeist.config.json. For app bundles or servers, ensure the target’s buildCommand compiles your artifact and the outputPath points at the produced binary or bundle root.

2. Keep the daemon running

   poltergeist haunt

   The watcher streams filesystem changes to Watchman, debounces noisy saves, and queues builds smartly across multiple targets.

3. Launch through polter

   polter my-app --some-flag

   polter waits for the daemon to finish rebuilding, then execs the binary. Rerun the command whenever you want to relaunch; builds that finish while the app is running are immediately available.

4. Wire into app-specific reload hooks (optional)

   • Swift/Xcode: enable a target that builds your .app bundle, then use scripts or plugins that monitor the bundle for relaunch.
   • Electron/Web backends: chain commands (e.g., buildCommand: "pnpm build && touch tmp/restart.txt") so your framework’s watcher restarts automatically.
   • Mobile simulators or embedded devices: point outputPath at the packaged artifact and use post-build scripts to deploy.

Configuration tips:

• Tune settlingDelay and debounceInterval per target to avoid double rebuilds for large asset drops.
• Inject environment variables under the target’s environment block (e.g., SWIFT_HOT_RELOAD=1) so your app enables its live-update code paths.
• Add multiple enabled targets (UI, backend, integration tests). Poltergeist applies per-target priorities and rebuilds whichever a change touches first.

Poltergeist rebuilds in the background from the moment files change, so humans and coding agents can rely on polter <target> to run fresh binaries without bespoke scripting. Aliases (start/haunt), fuzzy target matching, and inline error reporting keep command usage predictable. For detailed agent playbooks, timeout strategies, and log streaming tips, see docs/agent-workflows.md.

• CLI reference
• Configuration guide
• Agent workflows
• Architecture overview
• Examples & E2E notes

• Node.js 22+ for CLI development
• Xcode 26+ for macOS app development
• Watchman for file watching

# Build from source
git clone https://github.com/steipete/poltergeist.git
cd poltergeist && pnpm install && pnpm run build

# Development commands
pnpm test                   # Run tests
pnpm run dev                # Auto-rebuild mode
pnpm run lint               # Code quality checks
pnpm run typecheck          # Type validation

# Navigate to macOS app
cd apps/mac

# Build and run
xcodebuild -project Poltergeist.xcodeproj -scheme Poltergeist build
open Poltergeist.xcodeproj

# Code quality
./scripts/lint.sh           # SwiftLint checks
./scripts/format.sh         # swift-format fixes

Our comprehensive CI/CD pipeline ensures code quality across both platforms:

• Multi-platform testing: Node.js 22/24 on Ubuntu, macOS, and Windows
• Swift 6 validation: Strict concurrency checking and modern Swift practices
• Code quality: SwiftLint, swift-format, Biome, and TypeScript checks
• Automated releases: Dual-platform releases with both CLI (.tgz) and macOS app (.dmg/.zip)
• Test coverage: Comprehensive coverage reporting with Codecov

poltergeist/
├── src/
│   ├── builders/           # Target-specific builders
│   ├── cli.ts             # Command line interface  
│   ├── poltergeist.ts     # Core application logic
│   ├── priority-engine.ts # Intelligent priority scoring
│   ├── build-queue.ts     # Smart build queue management
│   ├── state.ts           # State management system
│   └── watchman.ts        # Watchman file watching
├── test/                  # Vitest test files
└── dist/                  # Compiled JavaScript output

For detailed information about releases, bug fixes, and improvements, see CHANGELOG.md.

MIT License - see LICENSE file for details.

Created and maintained by Peter Steinberger

Built with these excellent open source projects:

• Watchman - Facebook's efficient file watching service
• Commander.js - Complete CLI framework
• Zod - TypeScript-first schema validation with static type inference
• Winston - Universal logging library with support for multiple transports

• TypeScript - JavaScript with syntax for types
• Vitest - Blazing fast unit test framework
• Biome - Fast formatter and linter for JavaScript, TypeScript, and more
• TSX - TypeScript execute and REPL for Node.js
• TypeDoc - Documentation generator for TypeScript projects

• Chalk - Terminal string styling done right
• Ora - Elegant terminal spinners
• Node Notifier - Cross-platform native notifications

• Picomatch - Blazing fast and accurate glob matcher
• Write File Atomic - Write files atomically and reliably
• fb-watchman - JavaScript client for Facebook's Watchman service

• All contributors and users who have helped shape Poltergeist
• The open source community for creating these amazing tools