Monitoring coding agents without letting an app write to your config

How apps in this space find out what your agents are doing

The risk is real enough that AgentNotch's changelog, read the same day, records: "Live Prompts can no longer overwrite your agent's configuration, and every write leaves a backup." Backups and merges are the minimum; asking first is the point.

Tier one: nothing written

Every meter and the Cost card work with nothing written anywhere. Each reads, and never writes:

• The login its tool already saved on the Mac: Claude Code's Keychain item or credentials file, Codex's auth.json, Cursor's editor state, Gemini CLI's oauth_creds.json, Copilot's config folder. With it Notchmeter makes the same read-only status request that tool's own app makes. The token is read into memory for that request and never refreshed, stored, logged or forwarded.
• The transcripts and logs the tools already keep: the usage lines of Claude Code's and Cowork's transcripts and of Codex's session rollouts, for the Cost card; Cursor's own usage export, for its spend; and modification times alone, to decide how often to poll.

That is enough for what each plan has left, when each window resets, the pace, the run-out and the spend, every figure labelled with where it came from. It is enough to list a session, and no more, and 0.9.0 says which is which: with no hook installed the Sessions card lists the Claude Code, Codex, Cursor, Gemini CLI and Copilot sessions running in your terminals (this user's processes with a terminal, Claude Code's own session file and the tail of its transcript for the title, model and branch, and OpenCode's from its database), each marked detected, with working a guess from the agent's own status, a transcript written in the last thirty seconds, or its CPU. Three things still need the agent to say so, which is what a hook is:

• That a session exists for certain, and which project it is in when no process and no file says: a detected row is a guess from the outside, and the hook's row replaces it the moment the hook speaks.
• When a turn ends. agent-notch, which watches processes and transcripts and writes nothing, puts it plainly: "only the agent knows when its turn ends."
• That an agent is waiting for you, and answering it. There is no channel back to the agent without a hook.

A detected session can know that it is running, its project, its terminal and, for Claude Code, its title, model and branch; it cannot know that a turn has ended or that the agent is waiting, so it never shows a wait and never lights a finish, and the card ends with the one line that says what the hook adds: exact turn ends and answering from the notch. It is on by default (Settings › Assistants › Sessions › Find sessions without the hook), it reads and never writes, and the rules are in docs/accuracy.md.

Tier two: the hook, on your click

A hook is the agent telling Notchmeter what happened, the moment it happens: a turn started, a turn ended, a permission is waiting, a question has options. That is what makes the waiting dot, the finished tick, the news in the notch and answering from the notch possible. Here is exactly how it is written.

1. Only when you press it. Each assistant's page in Settings has its hook's Add button, and Show snippet… if you would rather paste it yourself; Settings › Integrations › Hooks lists where every assistant's hook stands, with a way to its page. The first launch offers the Claude Code hook once, as a button. No hook is ever installed without that click; after it, the app keeps the entries you installed up to date at launch unless you turn that off (below).
2. A backup first, beside the file: settings.json.bak-yyyyMMdd-HHmmss (or hooks.json.bak-…).
3. A merge, not a rewrite. Notchmeter's entry is appended under each event that lacks one. Hooks already there, their matchers and their order are kept, and so are the file's permissions. Nothing is written when every event already has the entry. A file that is not a JSON object is left untouched, and the button says why.

The one write that is not a click

If you move the app, a hook you installed points at the old path and goes quiet; if you update to a version that listens for more events, the entry you installed is out of date. So by default the app repairs its own entries at launch: after the same backup, it points them at the running copy and adds an entry for any event the current version listens for, leaves every other hook untouched, and never does it from a copy running out of a build folder. It never adds a hook for an assistant you have not installed one for. After a repair, Codex runs the changed entries only once you trust them again in /hooks, and the OpenCode plugin updates itself. If you want no write at all after the one you pressed, turn off Repair an out-of-date hook at launch in Settings › Integrations › Hooks, and use the Repair button on the assistant's page when you choose to.

The status line and the plugin

Install status line… sets Claude Code's statusLine after the same backup. A status line you already had is kept: Notchmeter runs yours with the same input and passes its output through, so Claude Code's bar still shows your line. The Claude Code plugin installs no hook and no status line; those stay a button in Settings.

What the hook sends

The event's name, the session id, the project folder's name, the branch and the permission mode; where the hook's own terminal is (the terminal app, its tab or pane id, the tty, tmux and kitty ids), so a click on a session can bring that terminal forward; the first line of a prompt, which the app drops on arrival unless Show what a session is working on is on, and the items of the session's task list, whose words it drops the same way; the model, where the assistant names one; and for a permission, the tool's name and a bounded summary, never the raw input. Claude Code's transcript path never leaves the command. Cursor's does, since 0.9.13: Cursor's hooks never report its to-do list, so the app reads the list from the conversation's transcript. It goes over a Unix socket on the Mac that accepts a connection only from a copy of Notchmeter whose code signature matches, and it fails open: with the app not running, or anything wrong, the agent carries on as if no hook existed. docs/hooks.md lists every field for every assistant.

Undoing it

• Claude Code: delete the groups whose command contains Notchmeter … --hook from ~/.claude/settings.json, and the statusLine entry, restoring your own if Notchmeter chained it; or restore the .bak copy.
• Codex, Cursor, Gemini CLI: delete the entries whose command contains --hook --tool codex, --tool cursor or --tool gemini, or restore the backup.
• Kimi Code: delete the [[hooks]] tables whose command contains --hook --tool kimi from ~/.kimi/config.toml, or restore the backup.
• OpenCode: delete ~/.config/opencode/plugins/notchmeter.js.
• Copilot CLI: delete ~/.copilot/hooks/notchmeter.json and restart Copilot.

Switching an assistant off in Notchmeter, or quitting it, also stops its hook having any effect; the command still runs and exits at once.

Choosing

If you want to know what each plan has left and what the work is costing, tier one is enough and nothing is written. If you want to see your sessions, know the moment an agent needs you, and answer it without finding the terminal, add the hook for that one assistant. You can start with the first and add the second later, one assistant at a time, and take it out again whenever you like.