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

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

## When to Use
- 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

## When NOT to Use
- The project already has a sufficient built-in watch mode (e.g., Vite, webpack-dev-server)
- Working on a single-file script that does not need compilation
- 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

## Installation
- **homebrew**: `brew tap steipete/tap && brew install steipete/tap/poltergeist`
- **npm**: `npm install -g @steipete/poltergeist`

---
Source: https://littlescripts.sh/tools/poltergeist
