claudeers.
// Developer Tools

perch

Where you left off, in the notch. A macOS app for people running Claude Code, Codex, OpenCode and pi sessions at once.

// Developer Tools[ cli ][ api ][ web ][ claude ]#claude#claude-code#codex#developer-tools#macos#notch#swift#devtools◷ MIT$open-sourceupdated about 1 month ago
Actively maintained
100/100
last commit 5 days ago
last release 5 days ago
releases 35
open issues 3
// star history

Install with your AI

Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.

Install and set up perch (release-binary project) into my current project.
Found on https://claudeers.com/perch
Repo: https://github.com/asafofer/perch
Homepage/docs: https://perchapp.dev
Detected install method: release-binary → inspect the README
Category: devtools. Platforms: cli, api, web.
Read the repo's README for exact setup and env vars, then install it and wire it into my project.

Claudeers Health Verdict:
active; community-verified: false. Confirm the source before running anything.
// or install directly (release-binary)

Grab the latest release asset from GitHub.

# download a build from https://github.com/asafofer/perch/releases
// or clone
git clone https://github.com/asafofer/perch

// compatibility

Platformscli, api, web
Operating systems—
AI compatibilityclaude
LicenseMIT
Pricingopen-source
LanguageSwift

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

perch

Perch

The fastest way back to your agents.
Perch lives in your Mac’s notch. See what your coding agents did, answer them, jump back in.

perchapp.dev · Features · Install · Shortcuts · Privacy · Development

Perch in the notch: Claude asks to run a command, a flip to a session at work with its orb beside the step, all sessions with their status rings, then a session you are not in finishing while you work

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, its project, what the agent did and the next step when there is a real one. While a session works, it says what it is doing right now.
  • 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 folds to small wings until you answer. An answer from the notch or a card says it went: the notch folds to one line that reads Sent, with a blue paper plane.
  • What needs you. With live status on, Claude Code, Codex, OpenCode and pi 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 or cmux split. 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 (its Claude Code and Codex workspaces), and Claude Code, Codex, OpenCode or pi in any terminal, with exact tab switching in Terminal, iTerm2, Ghostty and cmux, and exact panes inside herdr and tmux.

Install

Requirement
macOS26 or later, on Apple silicon. A notch is optional: other displays get a small tab at the top centre.
AgentsThe Claude app, the Codex app, Conductor, or Claude Code, Codex, OpenCode and pi in a terminal (herdr, tmux and cmux included).
To buildXcode 26 and Node 20 or later.

Download. Get Perch.dmg from the latest release, open it and drag Perch onto Applications (the window shows you where). Perch is signed and notarized by Apple, so it opens like any app from the internet. After that Perch looks for a new version every hour and tells you with a quick peek in the notch; press Update (in the list, or click the peek) and it installs and restarts when nothing is on screen (the menu has Check for updates).

Build from source.

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

ActionKeys
Open the cardHover the notch, or tap ⌘ ⌥
Where was I⌃ ⌥ P
All sessions⌃ ⌥ L, or ← from the card
Next or previous session↑ ↓
Open the sessionReturn
Allow or denyA / D
Answer a question1 to 4
ReplyR
Not now (30 minutes, 2 hours, tomorrow)N
Settings⌘ ,
CloseEsc

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 sends nothing anywhere. 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 OpenCode and pi a plugin file of Perch's own (~/.config/opencode/plugins/perch.js, ~/.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.

PermissionUsed forWithout it
Accessibility⌘ ⌥, and typing a reply into the Claude or Codex appReplies are copied for you to paste
AutomationSwitching to the exact terminal tab or cmux split and typing a reply into itThe terminal comes forward and you find the tab
FilesReading project folders (macOS asks once per folder)That project is skipped

How it works

flowchart LR
  A["Session files<br>~/.claude, ~/.codex, OpenCode, pi"] --> C["PerchCore<br>scan, parse, state"]
  B["Hooks (optional)<br>local socket"] --> C
  C --> D["Snapshot (JSON)"]
  D --> E["Web view in the notch<br>ui/app.js"]
  E -- "your choice" --> C

A native AppKit shell owns the notch panel, hotkeys and the hook socket. PerchCore decides everything (which sessions show, their status, what the notch does) and is fully tested. The interface is a small web view that only draws the snapshot it is given and reports what you chose.

Development

Read AGENTS.md first: architecture, workflow, design rules and known pitfalls. CONTRIBUTING.md says how a change goes in and what CI checks.

cd ui && npm install && cd ..           # once
swift test                              # logic tests
./scripts/run.sh --show                 # build, launch and open the card
cd ui && python3 -m http.server 8765    # then open http://localhost:8765/design.html

ui/design.html is the real interface with sample data and every state on one page. New UI is designed there first.

PathContents
Sources/PerchCoreState machine, geometry, session scanning, transcript parsing, live status. Pure and tested.
Sources/PerchThe AppKit shell: panel, web view, hotkeys, hook socket.
ui/The interface: plain JavaScript and Tailwind, Inter bundled.
scripts/Run, package, install, signing certificate, app icon and the README GIF.
Troubleshooting
  • The card never appears on its own. It waits until you have been away for the "Come back after" time, 20 minutes by default. To test it quickly: ./scripts/run.sh --idle 15.
  • macOS asks for permissions after every build. Run ./scripts/make-dev-cert.sh once so builds are signed with a stable identity.
  • Perch asks for Accessibility again after an update. 0.4.0 is the first release signed by Apple, and macOS ties Accessibility to the signature, so it asks once more. Press Allow on the What's new card (or in Settings) and turn Perch on in System Settings.
  • Accessibility is on but Perch still waits. Remove Perch from the list with the minus button, add it again and restart Perch. Setup has a Restart button for this.
  • The list is empty. .build/debug/Perch --dump prints what Perch finds in ~/.claude/projects, ~/.codex/sessions, OpenCode's database and ~/.pi/agent/sessions, and which agents are running, in which terminal, herdr or tmux pane or cmux split. Headless runs (claude -p, codex exec) are not listed; pi -p and opencode run save sessions like any other, so they are.
  • Status lags or guesses. Turn on live status in Settings. Without it Perch reads the transcripts, which can only guess when an agent is waiting for you.
More scripts
ScriptWhat it does
./scripts/package.shBuilds a release and writes build/Perch.zip for sharing.
./scripts/make-icon.shRenders docs/assets/icon.svg into the app icon and icon.png.
./scripts/record.shFilms the design page's sample flow into docs/assets/perch.gif. Needs ffmpeg; headless.
./scripts/agents-demo.shherdr with pi, OpenCode, Claude Code and Codex side by side, and pi alone, in cmux, for trying Perch live.

Roadmap

  • More sources: Cursor
  • An optional sound and haptics

Credits

Wallpapers by Raycast. The working orb is Thinking Orbs by Yogesh (MIT). Set in Inter (SIL Open Font License 1.1, ui/dist/fonts/OFL.txt).

License

MIT.

// faq

What is perch?

Where you left off, in the notch. A macOS app for people running Claude Code, Codex, OpenCode and pi sessions at once.. It is open-source on GitHub.

Is perch free to use?

perch is open-source under the MIT license, so it is free to use.

What category does perch belong to?

perch is listed under devtools in the Claudeers registry of Claude-compatible tools.

38 views
★ 31 stars
unclaimed
updated about 1 month ago

// embed badge

perch on Claudeers
[![Claudeers](https://claudeers.com/api/badge/perch.svg)](https://claudeers.com/perch)

// retro hit counter

perch hit counter
[![Hits](https://claudeers.com/api/counter/perch.svg)](https://claudeers.com/perch)

// reviews

// guestbook

0/500

// related in Developer Tools

🔓

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Curs…

// devtoolsaffaan-m/⟨JavaScript⟩★ 307,864◷ MIT[ claude ]
🔓

Makes your AI agent think like the laziest senior dev in the room. The best code is the code you never wrote.

// devtoolsDietrichGebert/⟨JavaScript⟩★ 187,728◷ MIT[ claude ]
🔓

AI coding assistant skill (Claude Code, Codex, OpenCode, Cursor, Gemini CLI, and more). Turn any folder of code, SQL schemas, R scripts, shell scripts, docs,…

// devtoolssafishamsi/⟨Python⟩★ 147,800◷ MIT[ claude ]
🔓

Use Garry Tan's exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA

// devtoolsgarrytan/⟨TypeScript⟩★ 140,465◷ MIT[ claude ]
→ see how perch connects across the ecosystem