The app was CodexBar 0.43.0, Apple-notarized, with its refresh interval set to one minute. To show me a usage number, it spawned the Claude CLI. The CLI did not run in a clean sandbox. It read my ordinary Claude configuration, which meant every probe also initialized my two MCP servers (Context7 and Serena) and my Chrome integration. Chrome arrived with its GPU process, network service, storage service, and a swarm of renderers restoring tabs and extensions.

The measurements from that afternoon are in the repository, with timestamps. Two probes started at 14:56:48 and 14:57:48, one minute apart, both children of CodexBar's watchdog. Renderers individually took 30 to 111 percent of a core. Free memory fell from roughly 220,000 pages to about 4,000; compressed memory went from zero to over 100,000 pages; WindowServer climbed to 33–40 percent CPU, and input stopped reaching the screen. I killed CodexBar at 14:58:42 and watched for two more minutes. No new probes appeared.

To be fair to CodexBar, it was not the only load on that machine. Two USB display tools (DisplayLink and InstantView) were also running, and they amplify anything that stresses WindowServer. But the periodic trigger, the thing that turned background weight into a frozen desktop every sixty seconds, was a menu bar app reading usage the expensive way.

Reading usage should not cost a CLI

I went through CodexBar's GitHub issues afterwards, about two hundred of them, and the same design shows up everywhere. When your data source is "ask the CLI," and the CLI is a full agent harness, every refresh carries the weight of your whole setup. The more MCP servers and integrations you configure, the heavier the menu bar update becomes.

The issue tracker makes the pattern concrete:

• #1844: an hourly "delegated CLI refresh" recovery path called /usr/bin/open and launched the user's default browser, in a fast retry loop every 20 seconds to 3 minutes.
• #2052: background Claude probes triggered CLI auto-update downloads because DISABLE_AUTOUPDATER=1 was never set. Ninety gigabytes of traffic in three days, and 257 to 495 Claude CLI processes spawned per day.
• #2251: every usage probe minted a new empty Claude session. Thirty-six phantom sessions accumulated in the account within weeks, and the probes started tripping Anthropic's rate limits.
• #2241: the CLI probe succeeded 23 times out of 268, an 8.6 percent hit rate. On failure it threw away the cached snapshot, leaving gaps of up to 110 minutes in the displayed data.
• #1999: two CodexBarCLI processes grew to 75 GB combined on a 48 GB machine and took the whole system down with a jetsam OOM.

None of these are carelessness. They are what happens when a passive monitor keeps booting an active agent, one probe at a time.

The files were already there

The alternative was sitting on disk the whole time. Coding agents record their own work. Claude Code writes ~/.claude/projects/**/*.jsonl. Codex writes ~/.codex/sessions/YYYY/MM/DD/*.jsonl. Qwen writes chat JSONL plus a usage_record.jsonl. Gemini writes event-sourced session JSONL. Cursor keeps its state in a SQLite database (state.vscdb), which AgentBar reads directly through the sqlite3 C API instead of asking Cursor for anything.

Everything AgentBar shows comes from those files. Daily token usage, quotas, per-model breakdowns, sixty days of session history, the graph of which agent called which, even the "waiting for your approval" state. That last one is not a heuristic. For Claude, it is read from the tail of the raw JSONL: an unfinished tool_use record with no matching result means the agent is blocked on a human, and AgentBar pins those rows to the top.

Claude's quota numbers come from ~/.claude/usage-watch/rate-limits.json, a file the Claude CLI itself writes after each exchange. AgentBar never asks a server and never starts a process to get them.

Enforced, not promised

"Read-only" is easy to claim and hard to keep, so AgentBar does not rely on discipline. Two mechanisms make it structural.

At runtime, ProcessGuard diffs the system process table with sysctl around every fetch. If a refresh ever spawns a forbidden child (Node, Python, npm, uv, a browser, an MCP server), the monitor notices its own transgression and reports it. In the test suite, NoProcessSpawnTests goes further: it registers ten MCP servers into a Claude configuration, runs a hundred refresh cycles against it, and fails the build if a single Node, Python, npm, uv, Chrome, or MCP process appears. The test is the receipt.

The rest of the design follows from the incident list above. A self-monitor measures AgentBar's own CPU and RSS with getrusage and task_info, and stops automatic refreshes if it ever crosses a threshold. Failed fetches do not blank the UI; the last good value stays on screen with its timestamp, stale-while-revalidate, which is the direct opposite of issue #2241. The shortest refresh interval on offer is five minutes. There is no one-minute option, by design. Refreshes are single-flight per provider, staggered seconds apart, and a provider that keeps failing gets its circuit breaker opened for fifteen minutes.

The only place AgentBar spawns subprocesses at all is the tool updater, on demand, with hard timeouts, and only when you click it. The Diag tab shows the books: last fetch duration, CPU time, peak RSS, files read, records parsed, and forbidden processes spawned. That last counter is always zero.

What you give up

Reading files has a cost, and it is honesty about that cost that separates a monitor from an ad.

File reading sees what the agent has already flushed to disk, not live API truth. Quota numbers are exactly as fresh as the file that carries them. Run-state detection is precise for Claude, whose log tails make the state explicit, and best-effort for Codex, Qwen, Gemini, and Cursor, where it is inferred from conversation turns. Cost figures are estimates against a model price table, and they may well be covered by a subscription; the UI says "estimated" every time. Cached tokens are priced separately from generated ones so estimates do not double-bill, which is the bug behind CodexBar's issue #1796, where costs ran 2.7 to 4.6 times too high.

And an agent that keeps no local records cannot be watched this way, full stop. For the rare case where a provider's data only exists remotely, AgentBar has a remote usage query, but it is opt-in, configured per provider, and the single exception to the read-only rule. Nothing leaves the machine by default.

The quiet part

The fix that afternoon was quitting an app. The reason to write a new one was the realization that "monitor" and "spawn" had no business being the same verb. A usage meter should get heavier when your agents work harder, never when you configure more tools.

My Mac has been quiet since, which is an observation about my Mac, not a promise about yours. The promise lives in the repository: in ProcessGuard, in NoProcessSpawnTests, and in a Diag tab that prints the receipt on demand.

Later you want the whole chain. Who called whom, with what command, and what each one is doing right now. In a service backend this is what distributed tracing is for. A trace context propagates across each hop, a collector assembles the spans, and a UI draws the waterfall. The catch is the instrumentation. Somebody has to inject the context and run the collector.

You installed none of that. No hooks in the agents, no tracer library, no daemon watching process creation. So the fair question is how a trace can exist at all.

The short answer is that it does not exist, in the tracing sense. Nothing was captured at the boundary. AgentBar reconstructs the graph afterwards, from records the agents wrote for their own reasons, and it marks every connection that required a guess.

The records were already there

Coding agents keep transcripts. Claude Code writes ~/.claude/projects/**/*.jsonl. Codex writes dated session JSONL under ~/.codex/sessions/. Qwen and Gemini keep their own JSONL. Cursor stores state in a SQLite database, which AgentBar reads directly through the sqlite3 C API rather than asking Cursor anything.

These files exist so the agent can resume a session and show you history. They are a side effect of the agent working, not of the agent being watched. AgentBar reads them and nothing else. It spawns no CLI, installs no hook, injects no tracer. The companion piece on reading files instead of spawning agents covers why that constraint matters. Here the point is narrower: the raw material for a trace was on disk the whole time.

A trace built this way is forensic. It works on what already happened, from artifacts left behind. Live telemetry reports truth as it crosses a boundary. Reconstruction reads the receipts and infers what most likely happened.

Finding the moment one agent calls another

The first job is to notice a crossing at all. AgentBar's EdgeDetector scans the parent run's conversation turns, looking only at tool and assistant turns, since user and system turns do not execute commands. Within those turns it splits each line at the shell separators (&&, ;, |, a lone &) and asks what each segment actually runs.

The tokenizer is deliberately shallow, and the source says so. It skips leading environment assignments (FOO=bar) and command wrappers (nohup, sudo, env, time, and friends), then takes the first real token and strips any path. nohup codex exec "…" reads as codex. /usr/local/bin/claude -p "…" reads as claude. Agents launched detached or under sudo are exactly the ones worth tracking, so the wrappers matter.

This is no shell parser, and the job does not require one. The task is to tell a launch command apart from prose. In codex exec "fix the tests", the agent name is the command token. In a sentence like "I asked claude to review the diff", it never is, so the sentence produces nothing. That single distinction removes most false positives before correlation even runs.

Each detection becomes an invocation: the command that crossed the boundary, the target agent, the timestamp of the turn that contained it, the parent's working directory, and the parent tool-call id when the command came from a tool result.

Turning an invocation into an edge

An invocation says the parent announced another agent. On its own it does not say which session that agent started. The binary could have run and exited inside the same turn, or the matching session might be one of several. AgentBar correlates.

For each invocation it filters the candidate sessions. A session qualifies when its provider matches the target agent, it started after the invocation and within a 60-second window, and, when both sides carry a directory, the project equals the invocation's working directory. A missing directory on either side is treated as unknown rather than as a mismatch. If several sessions qualify, the earliest start wins.

The result is an edge, and the data model is explicit about what kind. Every edge this path produces carries an .inferred confidence and renders as a dashed line. The model also defines a confirmed confidence, for a linkage passed across the boundary by an environment variable or session id. The file-only path never emits one. There is no cross-process signal to confirm against, only timing and directory coincidence, so AgentBar does not claim certainty it does not have.

This is the honesty the format allows. A solid line would mean the linkage was observed. A dashed line means AgentBar saw a launch command, saw a matching session appear shortly after in the same place, and concluded one caused the other. Usually that conclusion is right. The label exists for the times it is not.

What the graph draws

The Graph window opens from the Active tab in the menu bar and lays one human request out left to right, in the style of an X-Ray or Datadog trace map. Shape carries identity and color carries state, so the two never compete.

Circles are actor points: a human prompt, an agent run, a terminal marker. Squares are tool calls. Triangles are model thought, system notes, and approval waits. An agent run draws as a circle with a provider-specific border and a 6-point status dot, colored by one of five states: running, waiting for approval, completed, failed, or idle.

The node is a run, not a session. A session can contain many runs, each --resume or re-run of a thread, and parent-child edges are keyed to the run. Resuming a conversation does not orphan its children.

A child agent expands inline at the point where it launched. When bash runs codex exec …, that Codex draws as a child lane rather than a plain tool call. The parent lane descends into the child flow and merges back once it completes, and deeper nesting means deeper lanes. Consecutive thoughts of the same kind collapse into a single ×N node; clicking it opens every merged message, and clicking any shape opens an inspector with the thought content, the tool command and output, or, for an agent run, the model, tokens, cache hit rate, changed files, and every event. Large graphs stay navigable through two-direction scrolling, zoom from 35 to 200 percent, and a fit button.

State is a function of the log tail

Knowing who called whom is half the question. The other half is what each agent is doing now. AgentBar answers it the same way it builds the graph, by reading files and computing.

Each provider reduces its log tail to a small signal: the timestamp of the last record, the kind of the last event, whether a tool proposal sits unanswered, whether a terminal success or failure appeared. A pure classifier turns that signal into a state with a fixed priority. Failure wins first, regardless of recency. A fresh log with an unanswered tool proposal reads as waiting for approval. A fresh log with an open question reads as waiting for input. Fresh and still producing reads as running. A terminal stop that has gone cold reads as completed. Anything else is idle.

The freshness window matters. An approval wait only makes sense while the log is recent, so once a log goes stale the classifier stops claiming the user owes the agent anything.

Precision varies by provider, and the UI says so. For Claude the approval wait is read from the raw JSONL tail: an unfinished tool_use with no matching result record. For Codex, Qwen, Gemini, and Cursor it is a best effort inferred from conversation turns, and the state note carries the hedge. The menu bar's Active tab polls the session directories on a 10-second throttle, limits the live graph to the last three days and 25 runs per provider, reuses unchanged summaries and conversation tails from an in-memory cache, and pins anything waiting for approval to the top.

What reconstruction gives up

Reading receipts has a cost, and naming it is what separates a monitor from a demo.

Correlation can misfire. Two Codex sessions started in the same directory within a minute of the same invocation both look like candidates, and the earliest wins even if the other was the real child. The 60-second window and the directory check keep this rare rather than impossible. A crashed agent and one waiting for approval can leave similar log tails, which is why the state carries a note instead of a guarantee. Gemini is detected as a launch command but never correlates to a session, because AgentBar has no Gemini provider to match against yet. The invocation is recorded; the edge is not.

And the whole picture is only as current as the files that feed it. AgentBar sees what the agents have flushed to disk, not live process truth. A run that finished a second ago but has not written its terminal record still looks active.

None of this is hidden in the rendering. Inferred edges are dashed. Estimated states carry a note. The Analysis pane, a set of pure functions over the graph, reports per-provider tokens, estimated cost, cache hit rate, and run count, alongside graph health: maximum depth with a warning for chains stacked too deep, orphan runs, and edge count, with the longest run named as the bottleneck. It describes what it sees and flags where it guessed.

The trace was never collected. It was left behind, one JSONL line at a time, by agents that had no idea anyone would assemble their receipts into a graph. AgentBar's job is to read those receipts carefully, connect them only where the evidence supports a connection, and say plainly where it had to guess. The causal chain you wanted is on your disk. So is the honesty about how much of it is inference.