Notes on what agent-top does, why it works the way it does, and what it found on the way.
On a ChatGPT plan, Codex has a usage allowance measured over a rolling five-hour window, and a weekly one on top. Codex's /status command shows how much is left, in the session you type it into.
Codex also writes the same numbers into every session's rollout file, after every model response. agent-top reads them from there and shows them next to the session's tokens and cost.
agent-top reads files it did not write. Some of them record exactly what happened, some record part of it, and some leave agent-top to work the rest out. The figures on screen come from all three, and they sit next to each other in the same table.
So each figure carries a mark for which kind it is. This post lists the marks, what produces each one, and what to do when a number does not match the one your harness shows.
Run a few coding agents for a week and then look at your process list. Somewhere in it, if you are unlucky, is a node or python process that nobody asked for, parented to pid 1, holding eighty megabytes, doing nothing. It was an MCP server. The agent that started it finished hours ago.
This post is about how that happens, why it is worth catching early, and how agent-top shows it.
Tracing is an old idea from distributed systems: a request comes in, it fans out into work on several services, and if you want to know where the time went you need to see all of that work on one shared timeline, with the causal links between the pieces intact. A span is one piece of work with a start, an end, and a name. A trace is a tree of spans that all belong to the same request. The reason the idea generalized past HTTP services is that it doesn't actually care what the work is, only that it has a beginning, an end, and a parent.
An agent turn has exactly that shape. You send a prompt. The model thinks, then calls a tool, then thinks again about the result, maybe calls three tools in parallel, spins up a subagent that does the same thing one level down, and eventually replies. That's a trace. The model's thinking is a span. Each tool call is a span. The subagent's whole turn is a span containing its own spans. Nothing about applying tracing to this is a stretch; the only question is where the spans come from.
You have two Claude Code sessions open, a Codex thread inside the editor, and a Gemini CLI you started this morning and forgot about. Each one has a window. None of them has the whole picture. Which one is burning tokens right now? Which one is waiting for you? Which MCP server is still alive after the agent that started it went away?
agent-top is the whole picture, in one terminal. This post is the five parts of it I would show someone first: the problem each one answers, and what it looks like.