The fastest way back to your agents.
See when Claude Code, Codex, OpenCode, pi or Cursor finish or need you, answer them from your Mac’s notch, and jump back to the exact session.
perchapp.dev · Features · Install · Shortcuts · Privacy · Development
macOS 15+ on Apple silicon · Free and MIT · Local-only, no account · Signed and notarized by Apple
The real interface with sample data, on a wallpaper by Raycast.
## Why Perch Agents work while you are away, and they finish, stall or wait for an answer on their own schedule. When you come back to your Mac, Perch answers one question from the notch: **what was I doing, and what is waiting for me?** Then it gets you back in with one key. ## Features - **Where was I.** After a break, a card drops from the notch with the session, what the agent did and the next step, if there is one. - **While you work.** When a session you are not in finishes or asks for something, the notch grows with what happened and a row of buttons. A finish folds away on its own; a request waits as small wings until you answer. - **What needs you.** With live status on, Claude Code, Codex, OpenCode, pi and Cursor tell Perch the moment they finish or need your OK. Sessions that need you come first. - **Answer from the notch.** Allow or deny a command, or pick an answer to Claude's or OpenCode's question, without leaving what you are doing. - **Jump back in.** One key opens the exact session: in the Claude app, in Codex, in the terminal tab it runs in, or the exact herdr or tmux pane, cmux split or agterm pane. A session that has ended opens again where it last ran. - **Reply.** See the agent's last message and answer it, into a terminal session or into the Claude or Codex app. - **All sessions.** Every recent session in one list, grouped into what needs you, today and earlier, with its status at a glance. Type to filter. - **Yours.** Pick a character and its colour. It lives behind the notch and only comes out when there is something to say. Perch never takes the keyboard unless you ask for it, and it stays quiet about the session you are already in. **Works with** the Claude app (Code), the Codex app, [Conductor](https://conductor.build) (its Claude Code and Codex workspaces), [Cursor](https://cursor.com) (its agent chats, beta: tried with Cursor 3.23 and its Agents window), and Claude Code, Codex, [OpenCode](https://opencode.ai) or [pi](https://pi.dev) in any terminal, with exact tab switching in Terminal, iTerm2, Ghostty and Warp, and the exact split or pane in cmux, [agterm](https://github.com/umputun/agterm), [herdr](https://herdr.dev) and tmux. ## Install | Requirement | | |---|---| | macOS | 15 (Sequoia) or later, on Apple silicon. A notch is optional: other displays get a small tab at the top centre. | | Agents | The Claude app, the Codex app, Cursor, Conductor, or Claude Code, Codex, OpenCode and pi in a terminal (herdr, tmux, cmux and agterm included). | | To build | Xcode 26 or later and Node 20 or later. | **Download.** Get `Perch.dmg` from the [latest release](https://github.com/asafofer/perch-releases/releases/latest), open it and drag Perch onto Applications. It's signed and notarized by Apple, so it opens like any app. Perch checks for updates every hour and shows a quick peek in the notch when one is ready; press Update and it installs when nothing is on screen. **Build from source.** ```bash git clone https://github.com/asafofer/perch.git && cd perch ./scripts/make-dev-cert.sh # once: a stable local signing identity, so macOS remembers permissions ./scripts/install.sh # builds a release, installs it to /Applications and opens it ``` On first launch, a short setup walks you through your character, Accessibility, which apps to read and live status. You can run it again from Settings. ## Shortcuts | Action | Keys | |---|---| | Open the card | Hover the notch, or tap ⌘ ⌥ | | Where was I | ⌃ ⌥ P | | All sessions | ⌃ ⌥ L, or ← from the card | | Next or previous session | ↑ ↓ | | Open the session | Return | | Allow or deny | A / D | | Answer a question | 1 to 4 | | Reply | R | | Not now (30 minutes, 2 hours, tomorrow) | N | | Settings | ⌘ , | | Close | Esc | While the notch shows something that finished or asks for you, its buttons answer to keys too, and only then: ⌘ ⌥ Return switches to it, ⌘ R replies, ⌘ ⌥ Y or N allows or denies, ⌘ ⌥ 1 to 3 answers, and ⌘ ⌥ . puts it away. ## Privacy and permissions Perch reads the session files your agents already keep on your Mac, and your sessions, prompts and code never leave it. There is no account, analytics or telemetry. Perch goes online for two things only: - **Updates.** About once an hour it fetches the release list, `appcast.xml` in the public [perch-releases](https://github.com/asafofer/perch-releases) repo on GitHub, and downloads a new version only when you press Update. - **Send feedback,** when you use it. Your message, any screenshots you attach, your email if you give one and, if you choose, the Perch and macOS versions go to a small function (`feedback/`, on Vercel) that emails them to the maker of Perch. The card's words are your agents' own: the session's title, what the agent said it did, and a next step only when the agent stated one. **Live status** is optional. It adds one hook entry to `~/.claude/settings.json` and `~/.codex/hooks.json` that runs `~/.config/perch/hook`, and for Cursor four entries in `~/.cursor/hooks.json`, and for OpenCode and pi a plugin file of Perch's own (`~/.config/opencode/plugins/perch.js`, for OpenCode 1.4 and later and OpenCode 2, and `~/.pi/agent/extensions/perch.ts`). They talk to Perch over a local socket only you can use and do nothing when Perch is not running. Your config files are backed up the first time as `*.before-perch`, and turning live status off removes the entries and files. Codex asks you once to trust a new hook. | Permission | Used for | Without it | |---|---|---| | Accessibility | ⌘ ⌥, and typing a reply into the Claude or Codex app | Replies are copied for you to paste | | Automation | Switching to the exact terminal tab or cmux split and typing a reply into it | The terminal comes forward and you find the tab | | Files | Reading project folders (macOS asks once per folder) | That project is skipped | ## How it works ```mermaid flowchart LR A["Session files