🍕 Agenteria

Every Claude Code session becomes an oven in your menu bar. See what is cooking, what is blocked, what is finished, and how full each context window is.

Blocked · finished · compacting · cooking · still running

Install

macOS, with Claude Code already set up.

curl -fsSL https://agenteria.henrywhittle.com/install.sh | sh

Prefer to read it first? It is 30 lines. Or do it by hand:

git clone https://github.com/Whittle777/agenteria.git
cd agenteria && python3 install.py

That is the whole install. It adds the hooks, builds the menu bar app, and sets it to start at login. Nothing needs sudo and nothing lands outside your home directory. python3 install.py --uninstall takes it all back out.

What the ovens mean

Oven	State	Means
Orange flame	cooking	The agent is mid-turn.
Red `!`	blocked	Claude stopped and is waiting on you.
Golden pizza	ready	Finished and unreviewed.
Violet bars	compacting	Claude is squeezing its own context down.
Blue dots	still running	The turn ended but a backgrounded command has not.
Empty oven	idle	Running, but not doing anything.
Amber ⚠︎	context	Some session is past 80% of its window.

Click an oven

It brings that session's terminal to the front, and that is all it does. The match is exact, not a guess: the hooks report the tty and Terminal.app exposes the same string per tab. There is deliberately no dismiss button in the bar, so the way you clear a finished pie is by going back to the session and using it.

Context and tokens

Each ticket shows how much of its context window it has used, and the menu totals the tokens generated today. Read from the transcripts Claude Code already writes, incrementally, so polling stays cheap.

Why review is a state the agent cannot declare Agents report success and are sometimes wrong, and they finish turns while work is still running in the background. So "done" is not something a session gets to assert: a finished pie stays on the counter until you go back and look. That gate is the whole point of the thing.

Also included

A browser counter at 127.0.0.1:4646 with the full ticket detail, and ./cook, a pty wrapper that lets you type into a running session from the browser while the terminal stays completely live. Both are optional; the menu bar is the main event.

Status, honestly

It has only ever run on its author's machine. macOS, Terminal.app, Command Line Tools present, Claude Code 2.1.x.
Only Terminal.app is verified. iTerm2, WezTerm and kitty are written from their documented interfaces and have never been executed. They fail soft: if the exact-window path is wrong, clicking still brings the right application forward.
The iTerm2 path has been reviewed against iTerm2's scripting dictionary. That found a bug which would have stopped it ever engaging: iTerm2 ships as iTerm.app, so it was identified as "iTerm" and never matched the apps we try to raise a window in. Fixed, but reviewed is not the same as run.
Two internal Claude Code files are read, neither a public API: the transcripts, for context and token usage, and ~/.claude/sessions/<pid>.json, for whether a session still has work running after its turn ended. If either changes shape those readouts go blank. Nothing else is affected.
Background agents are found by transcript freshness, which is fuzzy at the edges. A subagent leaves no process and holds no file open, so the only signal is whether its transcript is still being written. An agent gone quiet inside a long tool call and one that just finished look the same for up to two minutes. It errs towards "still running".
The test suite covers off-turn detection and hook installation only. Everything else is verified by hand.

Issues and pull requests welcome, especially from anyone running a terminal that is not Terminal.app.

View on GitHub