Agent Notch infers what your agents are doing without asking them
The open-source alternative to vibe-island
At a glance
- What is it?
- Agent Notch shows a walking mascot beside the MacBook notch while a coding agent works and a green marker when it finishes, using only process inspection and transcript timestamps. It needs no configuration, and it documents its own thirty second imprecision in detail.
- Who is it for?
- Agent Notch suits anyone running one or two coding agents in a terminal on a Mac who keeps switching windows to see whether the work finished, and whose requirement is peripheral awareness rather than precise timing. Use agent hooks writing a state file instead when the transition itself matters, such as triggering something when a turn ends, since the README explains that no process-level inference can resolve turn boundaries exactly.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 59 days ago.
- What is it written in?
- Mainly Swift, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 17, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
A status light for agents you would otherwise keep checking
Agent Notch puts a small animated mascot beside the notch on a MacBook while a coding agent is working, and turns it into a green marker when that agent finishes. Two agents get their own slots, so one can finish while the other continues.
The problem it solves is attention. An agent working on a long task leaves you with nothing to do and no way to know when it is done except looking, so you look, repeatedly, which is the cost the agent was supposed to remove. A peripheral indicator converts that into something you notice rather than something you check.
The green state is specifically a notification rather than a status: the README describes it as meaning finished since you last looked, and focusing your terminal clears it. That distinction is the right one, because what you want to know is not whether an agent is idle but whether something happened while you were elsewhere.
Clicking opens a panel of sessions, and its organising decision is good. Each row is titled by your latest prompt rather than by the agent's own output, which is what you would use to recognise a session, with subagents folded under a dropdown and the actual model shown on the right.
Watching processes rather than asking the agent
The detection method is stated plainly and it explains both the strengths and the one flaw: no hooks, no interfaces, no accounts.
Every three seconds the tool lists processes to find agent binaries attached to a terminal, deliberately ignoring headless and background sessions. It then maps each process to the transcript file it holds open, or where that is not possible, to its working directory, noting that the two supported agents differ in whether they keep the transcript file descriptor open. The transcripts themselves supply prompts, snippets, model names and subagent structure, read from the conventional locations each agent writes to.
Liveness is then a hybrid rule. A process that is alive and has written to its transcript within the last thirty seconds counts as busy and the mascot walks. Alive and quiet counts as idle, showing nothing in the notch and a dimmed row in the panel. Gone for two consecutive polls counts as finished. Sessions idle for more than six hours drop off entirely, and activating any of six named terminal applications acknowledges finished agents.
That is an inference built entirely from what the operating system already exposes, which is why it requires no configuration at all.
The limitation is documented better than most projects document features
One section of the README deserves reading by anyone who writes software, regardless of interest in the tool.
It states that because busy and idle are inferred from transcript write times, and those writes are bursty, the mascot keeps walking for up to about thirty-three seconds after a turn actually ends, being the thirty second window plus the three second poll interval, and that quiet stretches within a turn are smoothed over.
It then explains why this cannot be fixed by trying harder: no process-level proxy, whether network activity, processor use or child processes, can fully resolve it, because only the agent knows when its turn ends.
It then names the precise fix, which is agent hooks writing a state file on prompt submission and completion, notes that the project it took its liveness model from does exactly that, and says the approach was deliberately skipped here to preserve the zero-configuration design. It closes by telling the reader that if the delay bothers them, that is the upgrade path.
Quantifying the error, explaining why the class of approach cannot do better, naming the alternative, and stating the trade as a deliberate choice is a complete account. Most projects would have written that the indicator is approximate.
Building it, and choosing a mascot
There is no release and no installer. The application is a single Swift source file compiled with the platform compiler.
swiftc -O main.swift -o AgentNotch
./AgentNotch &A single file compiled by one command is about as inspectable as a desktop utility gets, since a reader can read the whole thing before running it, which matters for something that reads your agent transcripts.
The mascot for one of the two agents is chosen by writing a name into a configuration file, with eight options listed and changes taking effect within a couple of seconds and no restart.
echo dewey > ~/.config/agent-notch/petThe window behaviour is the detail that decides whether a permanent overlay is tolerable. The collapsed window is transparent and click-through everywhere except the small indicator zone, so it does not block menu items or applications underneath, and in fullscreen spaces the bar spans the top edge. An overlay that intercepted clicks would be removed within a day; one that does not can stay.
What to weigh before running it
The first consideration is what it reads. To show you your prompts it reads your agent transcript files, which contain everything you have said to those agents. That processing is local and the tool has no network component described anywhere, and it is still worth knowing that a background utility is parsing your working history every three seconds.
The second is fragility. The tool depends on the internal file layouts of two agents, including specific directory structures and the grouping key one of them uses. Those are implementation details of other projects and can change without notice, at which point sessions stop appearing with no obvious cause.
Third, the sampling is deliberate. Headless and background sessions are ignored by design, so an agent you started in a way that is not attached to a terminal will not show up, which is correct for the intended use and surprising if you forget.
Fourth, distribution. No releases exist, the last push was on 2026-07-21, and installation means compiling it yourself, which excludes anyone unwilling to run a compiler and means no signed artifact.
Finally, licensing has two layers. The code is MIT, and the README states the mascot spritesheets are copyright of the company that publishes them, taken from their public asset location. That is disclosed rather than hidden, and it means the art is not yours to redistribute under the project's licence. This is not legal advice.
Hook-based reporting is the alternative, and the README says so
The alternative is the design this project explicitly declined, and it deserves credit for naming it: configure your agents to write a state file when a turn starts and ends, and read that instead of inferring from process behaviour.
The difference is exactness against setup. Hooks report turn boundaries precisely, because the agent knows when its turn ended, so the indicator changes the moment the work does with no window and no polling delay. The price is configuration in each agent, which must be maintained, can be broken by an upgrade, and has to be repeated on every machine.
Agent Notch takes the other side entirely. Nothing is configured, nothing is registered with the agents, and anything you start is picked up automatically, at the cost of an indicator that lags by up to half a minute.
For a peripheral awareness cue, which is what this is, half a minute of lag is unimportant, since you are being told an agent finished rather than being timed. For anything where the transition matters precisely, such as triggering a script when a turn completes, the hook approach is correct and this is the wrong mechanism. The README reaches the same conclusion and points the reader at it, which is the mark of a project confident about its own scope.
Editorial conclusion
Agent Notch suits anyone running one or two coding agents in a terminal on a Mac who keeps switching windows to see whether the work finished, and whose requirement is peripheral awareness rather than precise timing. Use agent hooks writing a state file instead when the transition itself matters, such as triggering something when a turn ends, since the README explains that no process-level inference can resolve turn boundaries exactly. Expect the indicator to lag by up to about thirty-three seconds, budget for compiling it yourself since there are no releases, and note that the mascot spritesheets are third-party copyright rather than covered by the project's MIT licence.
Frequently asked questions
Does Agent Notch require configuring hooks in my agents?
No. The README states there are no hooks, no APIs and no accounts. It polls every three seconds, finds agent processes attached to a terminal, maps them to their transcript files or working directories, and reads prompts, models and subagent structure from those transcripts.
Why does the mascot keep walking after my agent finishes?
Busy and idle are inferred from transcript write times, which are bursty, so the README states the mascot can keep walking for up to about thirty-three seconds after a turn ends, being a thirty second window plus a three second poll. Only the agent itself knows when a turn ends.
How do I install Agent Notch?
By compiling it. The application is a single Swift source file built with the platform compiler and then run in the background. There are no releases, so there is no prebuilt or signed artifact.
Does Agent Notch block clicks on things underneath it?
No. The README states the collapsed window is transparent and fully click-through except for the small indicator zone, so it never blocks menu items or applications beneath it, and in fullscreen spaces the bar spans the whole top edge.
Community notes