Skip to content

aeonfun/soul.md

Embody this digital identity. Read SOUL.md first, then STYLE.md, then examples/. Become the person—opinions, voice, worldview.

FileKindSize
SKILL.mdskill md4.5 KB
examples/_GUIDE.mdmarkdown1.5 KB
examples/ansem/MEMORY.mdmarkdown645 B
examples/ansem/README.mdmarkdown4.2 KB
examples/ansem/SOUL.mdmarkdown12.5 KB
examples/ansem/STYLE.mdmarkdown10.7 KB
examples/ansem/data/blknoiz06_all.jsonlother38.3 MB
examples/ansem/examples/bad-outputs.mdmarkdown6.1 KB
examples/ansem/examples/good-outputs.mdmarkdown8.7 KB
examples/bad-outputs.template.mdmarkdown2.2 KB
examples/elon-musk/MEMORY.mdmarkdown153 B
examples/elon-musk/QUICKSTART.mdmarkdown4.0 KB
examples/elon-musk/README.mdmarkdown3.5 KB
examples/elon-musk/SOUL.mdmarkdown10.5 KB
examples/elon-musk/STYLE.mdmarkdown5.8 KB
examples/elon-musk/data/sources.mdmarkdown1.2 KB
examples/elon-musk/examples/bad-outputs.mdmarkdown2.6 KB
examples/elon-musk/examples/good-outputs.mdmarkdown3.2 KB
examples/elon-musk/tests/prediction-test.mdmarkdown5.5 KB
examples/garry-tan/MEMORY.mdmarkdown428 B
examples/garry-tan/README.mdmarkdown2.1 KB
examples/garry-tan/SOUL.mdmarkdown13.3 KB
examples/garry-tan/STYLE.mdmarkdown9.2 KB
examples/garry-tan/data/influences.mdmarkdown2.6 KB
examples/garry-tan/examples/bad-outputs.mdmarkdown4.8 KB
examples/garry-tan/examples/good-outputs.mdmarkdown4.5 KB
examples/garry-tan/scripts/fetch_writing.pyscript4.0 KB
examples/garry-tan/scripts/fetch_x.pyscript3.7 KB
examples/garry-tan/scripts/fetch_yt.pyscript2.7 KB
examples/garry-tan/tests/platform_tests.mdmarkdown1006 B
examples/garry-tan/tests/prediction_test.mdmarkdown4.7 KB
examples/garry-tan/tests/results_gpt-4o-mini.mdmarkdown5.9 KB
examples/garry-tan/tests/run_weak_model.pyscript5.5 KB
examples/garry-tan/tests/scores_gpt-4o-mini.mdmarkdown3.6 KB
examples/garry-tan/tests/weak_model_test.mdmarkdown5.3 KB
examples/good-outputs.template.mdmarkdown2.4 KB
examples/hunter-biden/MEMORY.mdmarkdown1.0 KB
examples/hunter-biden/QUICKSTART.mdmarkdown3.3 KB
examples/hunter-biden/README.mdmarkdown6.1 KB
examples/hunter-biden/SOUL.mdmarkdown12.7 KB
examples/hunter-biden/STYLE.mdmarkdown9.1 KB
examples/hunter-biden/data/influences.mdmarkdown4.1 KB
examples/hunter-biden/data/x/tweets.jsonconfig96.0 KB
examples/hunter-biden/data/x/tweets.mdmarkdown65.7 KB
examples/hunter-biden/examples/bad-outputs.mdmarkdown7.4 KB
examples/hunter-biden/examples/good-outputs.mdmarkdown20.7 KB
examples/hunter-biden/tests/prediction-test.mdmarkdown4.2 KB
examples/karpathy/MEMORY.mdmarkdown515 B
examples/karpathy/QUICKSTART.mdmarkdown2.2 KB
examples/karpathy/README.mdmarkdown7.4 KB
examples/karpathy/SOUL.mdmarkdown15.3 KB
examples/karpathy/STYLE.mdmarkdown11.6 KB
examples/karpathy/data/github/karpathy_LLM101n_README.mdmarkdown2.3 KB
examples/karpathy/data/github/karpathy_arxiv-sanity-preserver_README.mdmarkdown6.8 KB
examples/karpathy/data/github/karpathy_char-rnn_README.mdmarkdown12.5 KB
examples/karpathy/data/github/karpathy_llm.c_README.mdmarkdown16.1 KB
examples/karpathy/data/github/karpathy_micrograd_README.mdmarkdown2.4 KB
examples/karpathy/data/github/karpathy_minbpe_README.mdmarkdown9.1 KB
examples/karpathy/data/github/karpathy_nanoGPT_README.mdmarkdown13.5 KB
examples/karpathy/data/github/karpathy_nn-zero-to-hero_README.mdmarkdown6.7 KB
examples/karpathy/data/influences.mdmarkdown4.9 KB
examples/karpathy/data/transcripts/7xTGNNLPyMI.en.txtmarkdown208.7 KB
examples/karpathy/data/transcripts/P6sfmUTpUmc.en.txtmarkdown108.9 KB
examples/karpathy/data/transcripts/PaCmpygFfXo.en.txtmarkdown96.3 KB
examples/karpathy/data/transcripts/SOURCES.mdmarkdown2.7 KB
examples/karpathy/data/transcripts/TCH_1BHY58I.en.txtmarkdown63.3 KB
examples/karpathy/data/transcripts/VMj-3S1tku0.en.txtmarkdown118.3 KB
examples/karpathy/data/transcripts/c3b-JASoPi0.en.txtmarkdown39.5 KB
examples/karpathy/data/transcripts/hM_h0UA7upI.en.txtmarkdown55.4 KB
examples/karpathy/data/transcripts/kCc8FmEb1nY.en.txtmarkdown105.3 KB
examples/karpathy/data/transcripts/l8pRSuU81PU.en.txtmarkdown213.9 KB
examples/karpathy/data/transcripts/q8SA3rM6ckI.en.txtmarkdown102.5 KB
examples/karpathy/data/transcripts/t3YJ5hKiMQ0.en.txtmarkdown52.9 KB
examples/karpathy/data/transcripts/zduSFxRajkE.en.txtmarkdown122.6 KB
examples/karpathy/data/writing/ai-short-peek.htmlother55.7 KB
examples/karpathy/data/writing/biohacking-lite.htmlother41.2 KB
examples/karpathy/data/writing/blockchain.htmlother297.3 KB
examples/karpathy/data/writing/forward-pass.htmlother14.6 KB
examples/karpathy/data/writing/lecun1989.htmlother25.0 KB
examples/karpathy/data/writing/medium.htmlother6.6 KB
examples/karpathy/data/writing/microgpt.htmlother93.8 KB
examples/karpathy/data/writing/phd.htmlother56.7 KB
examples/karpathy/data/writing/recipe.htmlother32.9 KB
examples/karpathy/data/writing/rl.htmlother54.4 KB
examples/karpathy/data/writing/rnn-effectiveness.htmlother79.9 KB
examples/karpathy/data/writing/software-2.0.htmlother235.3 KB
examples/karpathy/data/writing/state-of-cv.htmlother13.3 KB
examples/karpathy/data/x/README.mdmarkdown564 B
examples/karpathy/data/x/curated-tweets.mdmarkdown35.7 KB
examples/karpathy/data/x/posts-original.jsonconfig171.1 KB
examples/karpathy/data/x/profile.jsonconfig470 B
examples/karpathy/data/x/replies.jsonconfig105.5 KB
examples/karpathy/examples/bad-outputs.mdmarkdown6.2 KB
examples/karpathy/examples/good-outputs.mdmarkdown14.8 KB
examples/karpathy/scripts/fetch-data.shscript6.6 KB
examples/karpathy/scripts/weak-model-test.mjsscript15.2 KB
examples/karpathy/tests/prediction-test.mdmarkdown6.1 KB
examples/karpathy/tests/weak-model-results.mdmarkdown12.6 KB
examples/michael-saylor/MEMORY.mdmarkdown351 B
examples/michael-saylor/QUICKSTART.mdmarkdown3.5 KB
examples/michael-saylor/README.mdmarkdown6.5 KB
examples/michael-saylor/SOUL.mdmarkdown13.4 KB
examples/michael-saylor/STYLE.mdmarkdown7.0 KB
examples/michael-saylor/data/influences.mdmarkdown2.5 KB
examples/michael-saylor/examples/bad-outputs.mdmarkdown3.7 KB
examples/michael-saylor/examples/good-outputs.mdmarkdown7.0 KB
examples/michael-saylor/tests/prediction-test.mdmarkdown4.3 KB
examples/steipete/QUICKSTART.mdmarkdown5.1 KB
examples/steipete/README.mdmarkdown6.9 KB
examples/steipete/SOUL.mdmarkdown16.8 KB
examples/steipete/STYLE.mdmarkdown12.1 KB
examples/steipete/data/github/openclaw--openclaw.README.mdmarkdown84.0 KB
examples/steipete/data/github/openclaw--openclaw.VISION.mdmarkdown5.3 KB
examples/steipete/data/github/steipete--Aspects.README.mdmarkdown10.8 KB
examples/steipete/data/github/steipete--CodexBar.README.mdmarkdown8.5 KB
examples/steipete/data/github/steipete--InterposeKit.README.mdmarkdown11.0 KB
examples/steipete/data/github/steipete--Peekaboo.README.mdmarkdown7.4 KB
examples/steipete/data/github/steipete--Tachikoma.README.mdmarkdown3.9 KB
examples/steipete/data/github/steipete--VibeMeter.README.mdmarkdown13.3 KB
examples/steipete/data/github/steipete--agent-rules.README.mdmarkdown146 B
examples/steipete/data/github/steipete--agent-scripts.README.mdmarkdown5.8 KB
examples/steipete/data/github/steipete--birdclaw.README.mdmarkdown15.8 KB
examples/steipete/data/github/steipete--claude-code-mcp.README.mdmarkdown12.7 KB
examples/steipete/data/github/steipete--mcporter.README.mdmarkdown28.4 KB
examples/steipete/data/github/steipete--oracle.README.mdmarkdown28.3 KB
examples/steipete/data/github/steipete--poltergeist.AGENTS.mdmarkdown9.4 KB
examples/steipete/data/github/steipete--poltergeist.README.mdmarkdown13.5 KB
examples/steipete/data/influences.mdmarkdown10.7 KB
examples/steipete/data/transcripts/3-lessons-you-can-use-today.txtmarkdown10.9 KB
examples/steipete/data/transcripts/agentic-workflow-behind-openclaw.txtmarkdown12.6 KB
examples/steipete/data/transcripts/builders-unscripted-ep1.txtmarkdown31.4 KB
examples/steipete/data/transcripts/first-public-appearance-since-launch.txtmarkdown34.4 KB
examples/steipete/data/transcripts/i-ship-code-i-dont-read.txtmarkdown114.7 KB
examples/steipete/data/transcripts/lex-fridman-491.txtmarkdown158.5 KB
examples/steipete/data/transcripts/lex-fridman-clip-ai-agents.txtmarkdown25.9 KB
examples/steipete/data/transcripts/maximize-claude-code-subscription.txtmarkdown25.7 KB
examples/steipete/data/writing/2012-dont-call-willchangevalueforkey.htmlother59.8 KB
examples/steipete/data/writing/2012-hacking-block-support-into-uimenuitem.htmlother183.8 KB
examples/steipete/data/writing/2012-moving-on.htmlother62.2 KB
examples/steipete/data/writing/2012-nsurlcache-uses-a-disk-cache-as-of-ios5.htmlother54.5 KB
examples/steipete/data/writing/2012-pimping-recursivedescription.htmlother55.6 KB
examples/steipete/data/writing/2012-reboot.htmlother50.0 KB
examples/steipete/data/writing/2012-using-subscripting-with-xcode-4_4-and-ios-4_3.htmlother59.5 KB
examples/steipete/data/writing/2014-a-story-about-swizzling-the-right-way-and-touch-forwarding.htmlother112.5 KB
examples/steipete/data/writing/2025-applescript-cli-macos-complete-guide.htmlother110.7 KB
examples/steipete/data/writing/2025-automatic-observation-tracking-uikit-appkit.htmlother104.4 KB
examples/steipete/data/writing/2025-claude-code-anonymous.htmlother54.8 KB
examples/steipete/data/writing/2025-claude-code-is-my-computer.htmlother72.0 KB
examples/steipete/data/writing/2025-code-signing-and-notarization-sparkle-and-tears.htmlother101.6 KB
examples/steipete/data/writing/2025-commanding-your-claude-code-army.htmlother75.2 KB
examples/steipete/data/writing/2025-essential-reading-august-2025.htmlother78.7 KB
examples/steipete/data/writing/2025-essential-reading-july-2025.htmlother73.2 KB
examples/steipete/data/writing/2025-essential-reading.htmlother79.4 KB
examples/steipete/data/writing/2025-finding-my-spark-again.htmlother55.8 KB
examples/steipete/data/writing/2025-introducing-demark-html-to-markdown-in-swift.htmlother63.9 KB
examples/steipete/data/writing/2025-live-coding-session-building-arena.htmlother59.8 KB
examples/steipete/data/writing/2025-llm-codes-transform-developer-docs.htmlother59.9 KB
examples/steipete/data/writing/2025-logging-privacy-shenanigans.htmlother108.4 KB
examples/steipete/data/writing/2025-mcp-best-practices.htmlother69.0 KB
examples/steipete/data/writing/2025-migrating-700-tests-to-swift-testing.htmlother178.7 KB
examples/steipete/data/writing/2025-optimal-ai-development-workflow.htmlother67.8 KB
examples/steipete/data/writing/2025-peekaboo-2-freeing-the-cli-from-its-mcp-shackles.htmlother76.2 KB
examples/steipete/data/writing/2025-peekaboo-mcp-lightning-fast-macos-screenshots-for-ai-agents.htmlother67.1 KB
examples/steipete/data/writing/2025-poltergeist-ghost-keeps-builds-fresh.htmlother81.8 KB
examples/steipete/data/writing/2025-self-hosting-ai-models.htmlother114.9 KB
examples/steipete/data/writing/2025-shipping-at-inference-speed.htmlother70.1 KB
examples/steipete/data/writing/2025-showing-settings-from-macos-menu-bar-items.htmlother110.3 KB
examples/steipete/data/writing/2025-signature-flicker.htmlother69.5 KB
examples/steipete/data/writing/2025-startup-slop.htmlother69.7 KB
examples/steipete/data/writing/2025-stats-store-privacy-first-sparkle-analytics.htmlother58.6 KB
examples/steipete/data/writing/2025-stop-overthinking-ai-subscriptions.htmlother67.4 KB
examples/steipete/data/writing/2025-the-future-of-vibe-coding.htmlother88.9 KB
examples/steipete/data/writing/2025-understanding-codebases-with-ai-gemini-workflow.htmlother62.5 KB
examples/steipete/data/writing/2025-vibe-meter-2-claude-code-usage-calculation.htmlother71.3 KB
examples/steipete/data/writing/2025-vibe-meter-monitor-your-ai-costs.htmlother69.9 KB
examples/steipete/data/writing/2025-vibetunnel-first-anniversary.htmlother59.0 KB
examples/steipete/data/writing/2025-vibetunnel-turn-any-browser-into-your-mac-terminal.htmlother77.7 KB
examples/steipete/data/writing/2025-when-ai-meets-madness-peters-16-hour-days.htmlother70.4 KB
examples/steipete/data/writing/2026-openclaw.htmlother52.1 KB
examples/steipete/data/writing/command-your-claude-code-army-reloaded.htmlother59.4 KB
examples/steipete/data/writing/index.htmlother34.0 KB
examples/steipete/data/writing/just-one-more-prompt.htmlother59.7 KB
examples/steipete/data/writing/just-talk-to-it.htmlother80.8 KB
examples/steipete/data/x/curated-tweets.mdmarkdown42.1 KB
examples/steipete/data/x/openclaw.posts-original.jsonconfig68.4 KB
examples/steipete/data/x/openclaw.profile.jsonconfig478 B
examples/steipete/data/x/openclaw.replies.jsonconfig74.6 KB
examples/steipete/data/x/steipete.posts-original.jsonconfig95.5 KB
examples/steipete/data/x/steipete.profile.jsonconfig485 B
examples/steipete/data/x/steipete.replies.jsonconfig2 B
examples/steipete/examples/bad-outputs.mdmarkdown10.2 KB
examples/steipete/examples/good-outputs.mdmarkdown15.9 KB
examples/steipete/scripts/fetch-data.shexecutablescript11.4 KB
examples/steipete/scripts/pull-x.mjsscript3.9 KB
examples/steipete/scripts/weak-model-test.mjsscript17.7 KB
examples/steipete/tests/prediction-test.mdmarkdown13.2 KB
examples/steipete/tests/weak-model-results.mdmarkdown11.6 KB
examples/vitalik-buterin/MEMORY.mdmarkdown972 B
examples/vitalik-buterin/QUICKSTART.mdmarkdown3.3 KB
examples/vitalik-buterin/README.mdmarkdown6.9 KB

examples/steipete/data/github/steipete--poltergeist.README.md

View on GitHub
<div align="center">
  <img src="assets/poltergeist-logo.png" alt="Poltergeist Logo" width="200">
  
  # Poltergeist 👻 - The ghost that keeps your builds fresh—universal hot reload & file watcher

<a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js-24%2B-339933?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js 24+"></a>
<a href="https://github.com/steipete/poltergeist"><img src="https://img.shields.io/badge/platforms-macOS%20%7C%20Linux%20%7C%20Windows-blue?style=for-the-badge" alt="Platforms"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="MIT License"></a>
<a href="https://github.com/steipete/poltergeist/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/steipete/poltergeist/ci.yml?style=for-the-badge&logo=github&label=CI" alt="CI Status"></a>

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

</div>

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 `pnpm run dev` for native apps, with automatic configuration, notifications and a smart build queue. It stands on the shoulders of [giants](https://facebook.github.io/watchman/) 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](https://steipete.me/posts/2025/poltergeist-ghost-keeps-builds-fresh) - Learn how this tool was built using Claude Code and why it's designed to accelerate both human and AI development workflows.

## Installation

### Homebrew (macOS, ARM64)

```bash
brew tap steipete/tap
brew install steipete/tap/poltergeist
```

### npm (all platforms)

```bash
npm install -g @steipete/poltergeist
```

### Requirements

Poltergeist requires [Watchman](https://facebook.github.io/watchman/) to be installed:

- **macOS**: `brew install watchman`
- **Linux**: [Installation guide](https://facebook.github.io/watchman/docs/install#linux)
- **Windows**: [Chocolatey package](https://facebook.github.io/watchman/docs/install#windows) or manual install

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

## Features

- **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? Poltergeist 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

## Quick Start

### Installation

Install globally via npm:

```bash
npm install -g @steipete/poltergeist
```

### Basic Usage

1. **Automatic Configuration** - Let Poltergeist analyze your project:

```bash
poltergeist init
```

For CMake projects you can opt out of auto-configuring a build directory:

```bash
poltergeist init --cmake --cmake-no-configure
```

This preserves existing build trees and avoids running `cmake -B` automatically; targets are still detected from `CMakeLists.txt` and any existing build directory.

If a build directory already exists (e.g. `build/CMakeCache.txt`), Poltergeist will read it to infer the generator and targets without reconfiguring.

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:

```bash
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:

```bash
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.

### Live Status Panel

Need a full-screen dashboard? Run `poltergeist status panel` (or `poltergeist panel`) to launch the Ink-based status panel. It keeps targets, git metrics, and log tails visible, plus:

- **Adaptive git summaries**: Poltergeist polls `git status`/`git diff` every 5 s and either lists dirty files or—when `--git-mode ai` or `POLTERGEIST_GIT_MODE=ai` is set—shows a Claude-generated summary of the most important diffs.
- **Status scripts**: Each project can list lightweight health checks under `statusScripts`. Peekaboo, for example, prints `SwiftLint: 0 errors / 0 warnings [31s]` under the `peekaboo` target so you can spot lint regressions instantly.
- **Post-build tests**: Targets can declare `postBuild` commands that run automatically after a successful build; the panel renders their summaries (for example `Swift tests: success [2m]`) as second lines under the target.
- **Log-aware layout**: Selecting a target scrolls its log tail into view and the controls bar stays pinned to the last row, keeping the terminal clean.

See [docs/panel.md](docs/panel.md) for configuration details and troubleshooting tips (this is the status panel tracker the team keeps up-to-date).

## Hot Reload for Apps

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

   ```bash
   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**

   ```bash
   poltergeist haunt
   ```

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

3. **Launch through `polter`**

   ```bash
   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.

## Designed for Humans and Agents

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](docs/agent-workflows.md).

## Learn More

- [CLI reference](docs/cli-reference.md)
- [Configuration guide](docs/configuration.md)
- [Agent workflows](docs/agent-workflows.md)
- [Architecture overview](docs/architecture.md)
- [Examples & E2E notes](docs/test-e2e.md)

## Development

### Prerequisites

- **Node.js 24+** for CLI development
- **Xcode 26+** for macOS app development
- **Watchman** for file watching

### CLI Development

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

### macOS App Development

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

### CI/CD Pipeline

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

- **Multi-platform testing**: Node.js 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

<details>
<summary>Project structure and contributing guidelines</summary>

### Project Structure

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

### Contributing

Contributions welcome! Requirements:

1. Tests pass: `pnpm test`
2. Code formatted: `pnpm run format`
3. Linting passes: `pnpm run lint`
4. Types check: `pnpm run typecheck`

### Development Philosophy

- **No backwards compatibility**: Clean breaks over legacy support
- **Type safety first**: Compile-time safety over runtime flexibility
- **Performance over features**: Optimize for large projects
- **Simple over complex**: Clean APIs over extensive configuration

</details>

## Changelog

For detailed information about releases, bug fixes, and improvements, see [CHANGELOG.md](CHANGELOG.md).

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Author

Created and maintained by [Peter Steinberger](https://github.com/steipete)

## Acknowledgments

Built with these excellent open source projects:

### Core Dependencies

- **[Watchman](https://facebook.github.io/watchman/)** - Facebook's efficient file watching service
- **[Commander.js](https://github.com/tj/commander.js)** - Complete CLI framework
- **[Zod](https://zod.dev/)** - TypeScript-first schema validation with static type inference
- **[Winston](https://github.com/winstonjs/winston)** - Universal logging library with support for multiple transports

### Build & Development

- **[TypeScript](https://www.typescriptlang.org/)** - JavaScript with syntax for types
- **[Vitest](https://vitest.dev/)** - Blazing fast unit test framework
- **[Biome](https://biomejs.dev/)** - Fast formatter and linter for JavaScript, TypeScript, and more
- **[TSX](https://github.com/privatenumber/tsx)** - TypeScript execute and REPL for Node.js
- **[TypeDoc](https://typedoc.org/)** - Documentation generator for TypeScript projects

### User Experience

- **[Chalk](https://github.com/chalk/chalk)** - Terminal string styling done right
- **[Ora](https://github.com/sindresorhus/ora)** - Elegant terminal spinners
- **[Node Notifier](https://github.com/mikaelbr/node-notifier)** - Cross-platform native notifications

### Utilities

- **[Picomatch](https://github.com/micromatch/picomatch)** - Blazing fast and accurate glob matcher
- **[Write File Atomic](https://github.com/npm/write-file-atomic)** - Write files atomically and reliably
- **[fb-watchman](https://github.com/facebook/watchman)** - JavaScript client for Facebook's Watchman service

### Special Thanks

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

---

<div align="center">
  <strong>Keep your builds fresh with Poltergeist</strong>
</div>

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall