How to Wake an AI Agent Only When It Matters
August 14, 2026
Twenty agents finishing work is not the hard part. Finding out is.
A crew ships something at eleven at night. It posts to the shared file, the way it is supposed to. And then it sits there, done, waiting for a person who is asleep, or surfing, or simply not looking at that tab.
The fix is a watcher: a small program that stares at the shared file and wakes the right boss the moment their crew reports. I run one. It has been the difference between agents that work and agents that pile up.
The build is a bash loop. The part worth reading is the second half — the gate that decides who gets woken, because that is the part that decides what this costs you.
The one thing to hold onto
Waking a boss on every post is what makes a multi-agent setup cost a fortune.
The whole economics fits on one line: spend equals wakes times context times model tier. You can argue about the last two forever. The first one is the only one you fully control.
So the goal is not a watcher that notices everything. It is a watcher that stays quiet.
If eight out of ten posts wake somebody up, you did not build a watcher. You built a pager that bills you.
What you need
A shared file the agents already post to. A machine that stays on. A way to run a background job that restarts itself — launchd on a Mac, systemd on Linux.
That is it. No service, no queue, no vendor.
How it works
A loop checks the file every five seconds. Not by reading the whole thing — it takes a hash. If the hash is the same, nothing happened and it goes back to sleep. If it changed, it pulls the newest post and hands it to the gate.
The gate is the guide
Two layers, and the first one does almost all the work.
Layer zero is pure bash and costs nothing. It asks two questions of the new post. Is this a real signal — something shipped, something is blocked, something got assigned? And is it addressed to me, or to everyone?
Two cheap string checks. If the post is chatter, or it is addressed to a different boss, the loop sleeps. No model call. No tokens. Nothing spent.
One detail that matters more than it looks: a post with no recipient wakes everyone. Failing open is the right default, because a message nobody was told to read is exactly the message that gets missed.
Layer one is one small model call, and only on genuine ambiguity. A post that is clearly relevant already woke you. A post that is clearly noise was already dropped. What is left is the narrow middle, and that is worth a fraction of a cent to judge.
That call also fails open. When it cannot decide, it wakes you. A wasted wake costs pennies; a missed assignment costs a night.
The target is that eight out of ten posts never wake anyone. Mine hits that. It is the difference between a system you keep and one you turn off in a week.
The four layers that keep it alive
A watcher that dies quietly is worse than no watcher, because you stop checking manually and nothing tells you it stopped.
So it has four independent ways to stay up, and any one of them still alerts you.
The job runs under a supervisor set to restart it if it exits. It writes a heartbeat file, so you can see it is alive without watching the terminal. The installer heals itself if the setup drifted. And the loop is simple enough that little in it can break.
None of that is clever. It is four cheap answers to one question: what if this is dead and nobody tells me.
Three things that bit me
Keep the cursor untracked. The watcher stores its place — which post it last saw — in a small file. Commit that file and you have built a machine that feeds itself: the cursor updates, the update gets pushed, the push changes the shared file, the watcher fires on its own change. Leave it out of version control.
Background jobs have almost no environment. The supervisor starts your loop with a stripped-down path, so the command line tool you tested by hand is missing. When mine could not find it, every ambiguous post failed open to a wake, and my savings fell from eighty percent to about half. Nothing errored. It just quietly got expensive.
Background jobs have no keychain either. Whatever the gate uses to authenticate has to come from a plain file it can read, locked down to your user, kept outside the repo so it never gets committed.
All three cost me money before they cost me an evening. None of them announced themselves.
Only bosses get a watcher
This is the part that ties back to the chart.
A watcher is a boss tool. The person it wakes is the one who reviews the work and ships it. A worker does not need one. A worker needs to do its job and post when it is done.
So the rule in my setup is that a worker cannot start a watcher even when it decides it should. A hook blocks the call before it runs. It is not trusted to hold back. It is unable.
That distinction is the same one that makes the whole org chart safe. Preferences get written down. Real rules get built in.
Identity comes from the shell — each agent starts up knowing which role it is, so every post is signed and the routing question at layer zero has something to check.
Start here
Do not build the gate first. Build the loop.
Hash the file, wake on any change, and live with it for a day. You will be annoyed by lunchtime, and that annoyance tells you exactly which posts should never have reached you. That is your layer zero, discovered rather than guessed.
Then add the routing check. Then, only if you still have a middle, add the model call.
One file. One loop. Wake for less than you think.
This is the third part of the build. The operating system is the thing all of it runs inside, the org chart says who reports to whom, and the shared file is what this watcher is watching. Build those first or this has nothing to wake anyone about.
Hit a wall? Book a working session and we'll get it running.