Skip to content
CodexmacOS menu bar app

Every Codex session, at a glance.

Perch sits in your menu bar and watches every Codex session on your Mac — the CLI and Codex Desktop both. It shows what each one is doing, how much of your rate limit is left, and taps you on the shoulder when one needs a decision.

Get Perch — $29One-time purchasemacOS 13 or later
The Perch panel open from the macOS menu bar, showing four agent sessions with live state, model, context window and spend

How it works

Useful before you configure anything, live once you do

Two paths feed Codex support, and they degrade gracefully: if the hook half never gets set up, the scan half still carries the panel.

Rollout scan

Nothing to install to see something

Perch reads your Codex rollouts straight from ~/.codex, so the panel is populated the moment you launch it — including sessions that were already running. No hook, no config, no setup step between installing Perch and seeing your fleet.

Hooks

codex-report, for the live half

The hook is what turns a rollout history into a live view: state the instant it changes, a “needs you” the moment Codex asks, and Allow/Deny from the notification. Perch writes it into ~/.codex/hooks.json itself and chains onto hooks you already run.

Codex Desktop

Straight to the conversation

Codex is the one agent Perch can open by conversation rather than by window: a codex://threads link lands on the exact thread inside the desktop app. CLI sessions land in the exact terminal pane instead.

Hook trust

Codex won’t run a hook you haven’t trusted. Perch says so out loud

Codex requires every non-managed hook to be reviewed and trusted by hash before it will execute. Install an integration, change nothing else, and it sits there looking enabled while doing precisely nothing — no state changes, no alerts, no approvals. We know because it happened to us: on a live machine, none of Perch’s eight Codex hooks were trusted, and the integration read as on the whole time.

So Perch asks Codex directly which hooks it will actually run, and surfaces anything untrusted or stale-hashed in Settings with the fix attached. A silent no-op is the worst failure a menu bar app can have — you stop looking at it and never find out why.

What lands on the row

What Codex did, in plain words

Finished, with what it said

The “finished” notification shows the first line of Codex’s reply, rather than a bare “Codex finished its turn”. While it works, the row keeps the tool it’s running — “exec: npm test” — and the timer, for the whole of a long command.

Limits and errors, named

A turn that stops because you ran out of usage reads “Rate limited” and sends the rate-limit alert, not a “finished”. A turn that stops on any other error names the problem on the row.

Costs at current prices

Priced against OpenAI’s published list, GPT-6 and GPT-5.6 included, and each part of a session at the model that did it, so switching models doesn’t re-price what came before. Work on a model with no published price makes the figure end in “+”; if none of it can be priced, it reads “~$?” instead of looking free.

Sessions that stay on the list

A session in Codex’s background service stays for as long as its terminal is open, instead of dropping off after half an hour idle, and takes replies and Stop from your phone through that service, whatever terminal it’s in. Codex Desktop’s own short background threads no longer show up as extra rows.

Usage, limits and spend

Everything your account will tell you, on one strip

Credit balance

Your extra-usage credits, right beside the limit bars — so when the included allowance runs out you can see what’s left to spend instead of guessing.

Your plan, without a login

Codex reports your plan directly, so Perch can label it with no OAuth grant and no credential handling at all. It’s just there.

Rate-limit windows as bars

Both limit windows with their reset times, as a countdown or a clock. Perch warns you under ten percent and surfaces a rate limit the moment you hit one — on the Mac and as a push.

Per-model weekly bars

Opt in with a read-only OAuth grant and each model gets its own bar. Off by default, and everything above works without it.

Per-session cost is an estimate, derived from token counts, and Perch labels it as one rather than passing it off as a billed figure. Two things Codex doesn’t expose at all: lines changed per session, and a heads-up when a plan is ready for review.

Stats

A year of Codex, in one panel

Total tokens, sessions and active days; a contribution heatmap; current and longest streak; your longest session and busiest day; your favourite model and a full per-model breakdown. Filter to Codex alone, or set it against the other agents you run.

Codex sessions carry through to the iPhone and Apple Watch too — the fleet view, push alerts, Live Activities, and Allow/Deny from the notification on your phone or from your wrist.

The Perch stats panel showing a contribution heatmap, streaks, and a per-model token breakdown

Pay once for the fleet. Subscribe for the conversation.

Solo

$29one-time
  • Lifetime license — pay once, keep it
  • One Mac at a time; deactivate in-app to move
  • iOS companion, push alerts & Live Activities included
  • Notarized app with signed automatic updates
Buy Perch — $29

Team

$29per seat, one-time · 2+ seats
5
seats × $29 = $145
  • A license key for every teammate — not one shared key
  • Assign and revoke seats by email from your customer portal
  • Your seat is claimed on purchase; invite the rest by email
  • Same lifetime license and updates on every seat
  • Perch Pro is separate — each teammate who wants it subscribes in the iPhone app
Buy 5 seats — $145

Pro

Most popular
$4.99per month

or $29 a year

Launch price until 15 November, then $49 a year

  • A Mac app licence included, for as long as you subscribe — nothing separate to buy
  • Read your agents’ conversations from your iPhone, and reply straight back into the session
  • Works with your Mac locked, from anywhere your phone can reach it*
Get it on the App Store

Free to download. Pro is an in-app purchase.

* What Pro can reach depends on the agent and on where its session is running. Replying needs the session inside tmux, herdr or Rex (Droid, tmux or Rex) — Codex in its default mode and OpenCode use their own local servers instead — and it has to be switched on in Settings, because paying for Pro is not the same as consenting to remote input. Reading a conversation works wherever the session runs. Each agent’s own page says exactly what it supports, and what it doesn’t.

Questions Codex users ask

Can I reply to a Codex session from my phone?
Yes, with Perch Pro — the subscription bought in the iPhone app; the perpetual $29 licence does not include it. Codex was the second agent to get it. You can type a full message, multi-line included, straight from the iPhone app with your Mac locked, and stop a turn that's going wrong. In Codex's default mode Perch reaches the session through Codex's own background service, so it works whichever terminal Codex is in, and Stop works even while Codex is writing its answer. A session started with --no-daemon needs to be running in tmux, herdr or Rex, and there Stop does nothing in the few seconds while Codex writes out its final answer — Perch cannot tell that apart from the rest of the turn, so a Stop tapped right at the end may not land.
Why did Perch tell me my Codex hooks aren't trusted?
Because Codex won't run them until you say so. Codex requires every non-managed hook to be reviewed and trusted by hash — run /hooks inside Codex and approve them. Until you do, the hooks are installed but inert. Perch asks Codex directly which hooks it will actually execute, so it can tell you this instead of just looking broken.
What still works if I never trust the hooks?
The rollout scan, which is most of the panel: sessions, model, context, cost, usage bars and Stats all keep working. What you lose is the live half — instant state changes, the “needs you” alert, and Allow/Deny from a notification.
Do I have to edit ~/.codex/hooks.json myself?
No. Perch writes its hooks in and chains onto anything already there, so an existing setup keeps firing. Removing the integration from Settings takes them back out. The one step Perch can't do for you is the trust approval — that's Codex's, by design.
Does it work with Codex Desktop as well as the CLI?
Yes, and Perch labels which is which on every row. Codex Desktop gets the better jump of the two: clicking a session opens that exact conversation in the app, rather than merely raising it.
Is the cost figure exact?
No — for Codex it's an estimate derived from token counts, and Perch presents it as one. It is priced against OpenAI's published prices, each part of a session at the model that did it, and when some of the work ran on a model with no published price the figure ends in “+”. Rate-limit windows, your plan label and your credit balance are read values, not estimates.
Why does a Codex row say “hooks unconfirmed”?
Because replies and Stop need proof that Perch's hooks run in that session. At a Codex approval prompt a typed reply approves the command and Escape denies it, so Perch offers neither until Codex confirms that Perch's approval hook is installed, switched on and trusted — usually about a second — and, once the session has run a turn, until that session has sent a hook event. A session started with --disable hooks, -c features.hooks=false or a profile that turns hooks off says so on its row and gets no replies or Stop. So does a project whose own .codex/config.toml turns hooks off.
Does it work with Codex's background service?
Yes. Since Codex 0.157, sessions run in Codex's background service by default. Perch keeps them on the list for as long as they're open, and sends your phone's replies and Stop through that service, so they need no tmux or herdr. Starting Codex with --no-daemon runs it as an ordinary terminal session instead.
Does Perch tell me when Codex is down, or out of date?
Yes, both. Perch reads OpenAI's official status page, and when the part Codex uses is down, a red banner in the dropdown says so and links to the incident; a slowdown or maintenance shows as a small icon beside Codex's usage. Settings → General → Integrations shows your Codex version, and when a newer one is out on the channel you installed it from, how to update there. Perch never installs anything itself. Both checks are anonymous reads of public pages, and each can be turned off. Seeing an error and no banner? Is Codex down, or is it you?
Does my code leave my Mac?
No. Session state, rollouts and usage stay local. Data leaves only for features that require it: your paired iPhone (encrypted, over your LAN or your own tailnet), the push relay, and Polar for license checks.

Running Claude Code, Cursor, Devin, OpenCode, Amp, Antigravity, Droid or Muse Code too? Perch watches all 9 from one menu bar.