TL;DR: Poltergeist is an AI-friendly universal file-watcher that auto-detects any project and rebuilds them as soon as a file has been changed. It’s npm run dev for native apps, with automatic configuration, notifications and a smart build queue.

The Story

In agentic engineering, loop iteration speed is everything. While building Peekaboo, a macOS OS automation agent/cli/mcp written in Swift, my main friction point is build time. Swift isn’t famous for its fast compiler, and it’s especially noticeable once you start doing more web dev. In the time Swift is calculating dependencies, my TypeScript project already recompiled.

Worse, agents would sometimes forget to rebuild before testing, leading to debugging sessions on code that was already fixed.

Poltergeist fixes that. It builds in the background as soon as a file has been changed, accelerating the code/debug loop for both agents and humans.

So I wrote a quick bash script to watch Swift files and auto-rebuild in the background. Problem solved - for Swift. But then I realized this would be incredibly useful for any kind of project. I already had both the CLI and Mac app building automatically, and I figured out this could work for so many other use cases.

That’s when I decided to make this more of a thing - and went into another rabbit hole of building tools for my agents so I can be faster building tools for my agents.

The Universal Solution

I rewrote the entire system in TypeScript with one goal: make it work for any project, any language, any build system. Poltergeist became a universal file watcher that ‘haunts’ your projects.

While there are tools like watchexec, I didn’t find anything that was designed with an agentic engineering flow in mind. Poltergeist even detects if a human or agent calls it and adds helpful messages for agents to steer them to correct usage, even without polluting your AGENTS.ms file.

Everything happens invisibly. Save a file. By the time you’re ready to test, the fresh binary is waiting. For Mac apps, it even quits and relaunches automatically (yah I hear you, that’s a config setting). True hot reload would be nice, but that’s something for the future.

Channeling the Spirit

I’ve built Poltergeist completely with Claude Code. It’s a build tool and in the beginning I didn’t plan to make it a thing, only once I saw how useful it is, I decided to spend extra time and focus on it to make it its own thing. It started as a bunch of bash scripts, eventually I asked my agent to convert these into TypeScript and then kept iterating on it.

Sentences like “all autogenerated code” are insofar not meaningful anymore, as I’ve surely written (or rather: talked) 20 pages of prompts to perfect the design. With AI, English is the new programming language, and the fact that it’s TypeScript is more an implementation detail.

Why TypeScript? Agents can write it extremely well, the iteration flow is amazingly fast, compilation is instant, it’s cross-platform and Watchman has TypeScript bindings for it.

Dancing with Agents

You’ve already noticed - I love building developer tools and stuff that makes my life easier. Poltergeist seemed like such an obvious idea, that I was surprised that it didn’t exist yet.

I usually use my spec.md based approach for new projects, however this one evolved from some bash scripts to a full-blown dev tool, so there’s no spec, just a lot of prompts and iterating.

Building it almost felt too easy. Agents are extremely good at writing TypeScript and Go, so Claude one-shotted most of my prompts. I use WisprFlow and my prompts are usually quite long ramblings. I learned that talking more and giving reason to the things you want, really helps agents to understand and build the right thing.

The process is in most cases: long prompt + plan only ultrathink. Sometimes also: Give me a few options - esp. when I’m unsure what to do.

I don’t use Claude’s plan mode, simply saying “plan only” works equally well and fits my flow better (and don’t get me started on subagents). I often iterate multiple times on a plan before I type “y” to build it.

After it’s done I usually write “add tests + update docs” - adding tests per feature is much better than trying to add them at the end, plus if you have the feature in your context, writing tests will almost always uncover bugs in the feature implementation, and since the agent has all context it’s the best time to fix it. If I prompt everything at once they usually still stop and seem less focused - thus the explicit separation.

I add CI early on GitHub (again, simply ask cc) which is another layer of testing, that way I can make sure the project works with all OSes, not just on my Mac.

While writing this blog post, I asked Claude about his opinion on my language choice, and it didn’t give me the answer I expected. So - you can already guess - I did the obvious thing and let it loop a few hours to rewrite it in Go.

From Poltergeist to Poltergohst

Porting your project to a different language would have been nuts just a few months ago, these days I can just use agents and let them run in loops until it’s done. I saw this as an experiment to again try out open models and alternative CLIs and tweeted about it here - currently there are still too many bugs around Qwen 3 Coder and GLM 4.5 with OpenCode and Crush so I can’t recommend either.

They both have potential but just aren’t well-tested yet with open models and you’ll eventually encounter API errors and slowdowns. Which is unfortunate, since Qwen 3 Coder’s 1 Mio context window would have been perfect to absorb the whole project in one go and convert it.

My process with Claude Code was to convert all important files (sources, tests, not examples) to one big 1.1MB markdown file, and then copy/paste the complete text with the command “convert to Go”. That way you work around the 256KB limit that would make claude only read the file partially and slowly.

There are many websites to do the GitHub conversion, I prefer this one as it makes it easy to select file types and is fast+simple.

I didn’t use any todo structure for the conversion and simply nudged Claude a few times to continue - models tend to stop eventually (after ~30-60 min loops), no sophisticated prompts were required though.

While I built Poltergeist mostly with Claude Sonnet, I did the conversion with Opus 4.1, to celebrate its release. To improve code quality, I searched for an idiomatic, modern Go guide and ran a few refactors with that.

Ultimately I decided against Go, since I’m not super comfortable in it, and with Bun’s SPA mode, startup time is at ~44ms, and it’s perfect to distribute as a single binary (~20 MB compressed) on Homebrew.

There’s also the ecosystem argument that I didn’t see initially. Poltergeist uses Watchman under the hood which has superb TypeScript bindings, but no official Go bindings, leading to more code to maintain. The only Go binding project that exists hasn’t been maintained in years.

I kept this experiment on GitHub - check out poltergohst.

Seance Time

Pick homebrew if you’re on a modern Mac, otherwise npm. The npm version needs Watchman and Node.

# For modern macOS
brew tap steipete/tap
brew install poltergeist

# Windows, Linux, Intel Mac (Node 20+)
npm install -g @steipete/poltergeist

# Auto-detect and configure your project
poltergeist init

# That's it! (`start` works too, gotta keep the agents happy!)
poltergeist haunt

# Run your tool (always fresh!)
polter my-cli --help

Oh, before I forget - there’s also a native macOS menu bar app! It still needs some work so I haven’t released it yet, you can totally get the source though and play with it. With that you’ll always see if Poltergeist is compiling and if your build is red or green. Might just call it Ghostbuster.

Catch the Ghost

Poltergeist is a new kind of tool that’s built for humans and agents in mind - something we’ll surely see more of in the future. You install it once and then forget about it, since it fades into the background, your agent will use it automatically and you can use it or keep doing things the manual way. It’s the perfect invisible addition - you don’t see it, yet it’s here and helps you get results faster.

The best tools are invisible until you need them, then indispensable once you have them. Poltergeist is both - and it’s just one init away.