Perch
See the moment Claude Code, Codex, OpenCode or pi finishes or needs you — right from your Mac's notch.
- Source repo
- asafofer/perch
- Stars
- ★ 21
- Last updated
- today
- License
- MIT
- Primary language
- Swift
- FA score
- 64/100 · Some gaps
At a glance
- How it runs
- Works with
- Portable with changesCodex · Claude Code
- Cost
- Free, no paid service needed
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A developer running several Claude Code and Codex windows who steps away and wants to know which session is waiting on them.
- Not a fit if
- Developers on Windows, Linux, or Intel Macs
- Teams that don't need notch/menubar monitoring of coding agents
- Users unwilling to grant Accessibility, Automation, and Files permissions
- Source review
- 64/100 · Some gaps
What does this agent do, and when should you use it?
Perch is a native macOS 15+ menu bar and notch app that keeps tabs on coding agents: Claude Code, Codex, OpenCode and pi. It reads the session files those agents already write (~/.claude, ~/.codex, OpenCode's database, ~/.pi/agent/sessions) and can optionally add hooks that report status over a local socket. A native AppKit shell owns the notch panel, hotkeys and hook socket; PerchCore (pure, tested Swift) handles scanning, parsing and state; the visible interface is a small web view that only renders the snapshot it receives. From the notch you can allow or deny commands, answer agent questions, reply to the last message, and jump back to the exact session, terminal tab, cmux split or herdr/tmux pane. Everything stays local: no account, no analytics or telemetry, with network access limited to hourly update checks and user-initiated feedback. It is MIT licensed and distributed as a signed, notarized DMG.
Perch scans ~/.claude/projects, ~/.codex/sessions, OpenCode's database and ~/.pi/agent/sessions, parses transcripts, and derives each session's title, what the agent said it did, and a next step only when the agent stated one. PerchCore's state machine decides which sessions appear, which need you, and what the notch should do. With live status on, it adds one hook entry to ~/.claude/settings.json and ~/.codex/hooks.json and creates plugin files for OpenCode (~/.config/opencode/plugins/perch.js) and pi (~/.pi/agent/extensions/perch.ts); these talk to Perch over a local socket that only your user can access. The notch card then surfaces a finish or a request with buttons: A/D to allow or deny, 1–4 to answer, R to reply, Return to open the exact session (Claude app, Codex app, terminal tab, or a cmux split, herdr or tmux pane). ⌃⌥L lists every recent session grouped by what needs you, today and earlier, filterable by typing. Debug helpers include ./scripts/run.sh --show and .build/debug/Perch --dump.
- A developer running several Claude Code and Codex windows who steps away and wants to know which session is waiting on them.
- An engineer parallelizing pi and OpenCode in tmux, herdr or cmux who wants one key back to the exact pane.
- A Codex user who wants to approve commands or answer questions without switching windows after trusting the new hook.
- A Mac user without a notch who still wants a top-center tab showing when an agent finishes.
- A privacy-conscious solo developer who refuses to upload sessions or code to a cloud service.
- A contributor prototyping new notch UI states in ui/design.html against sample data before wiring them up.
How do you install or deploy this agent?
Download Perch.dmg from the latest release (signed and notarized by Apple), open it and drag Perch onto Applications.
# or 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 itBuilding needs Xcode 26+ and Node 20+; install the UI dependencies first:
cd ui && npm install && cd ..On first launch a short setup walks you through your character, Accessibility, which apps to read and live status; you can rerun it from Settings.
How do you use this agent?
Hover the notch or press ⌘⌥ to open the card; ⌃⌥P answers "where was I", ⌃⌥L lists all sessions (or press ← from the card). Navigate with ↑/↓, open with Return, allow or deny with A/D, answer with 1–4, reply with R, snooze with N (30 minutes, 2 hours, tomorrow) and close with Esc.
./scripts/run.sh --show # build, launch and open the card
./scripts/run.sh --idle 15 # test the auto-popup with a 15-minute idle threshold
swift test # logic tests
.build/debug/Perch --dump # print discovered sessions and running agentsTo work on the interface:
cd ui && python3 -m http.server 8765Then open http://localhost:8765/design.html for the real interface with sample data and every state on one page.
What are this agent's strengths and limitations?
- Distinctive notch-first interaction: allow, deny, pick an answer and reply without leaving the current window, with keyboard shortcuts such as A/D and 1–4.
- Precise jump-back targets: the Claude app, the Codex app, exact tabs in Terminal, iTerm2, Ghostty and Warp, plus the exact cmux split, herdr or tmux pane.
- Local-only by design: reads on-disk session files, no account, analytics or telemetry, with network access limited to update checks and user-sent feedback.
- Live status is optional and reversible: config files are backed up as *.before-perch on first use, and disabling removes the hook entries and plugin files.
- MIT licensed, source available, and the distributed DMG is signed and notarized by Apple.
- Requires macOS 15+ on Apple silicon, so Intel Macs, Windows and Linux users are excluded.
- Needs Accessibility, Automation and Files permissions; builds from source without make-dev-cert.sh prompt for permissions after every build.
- Since 0.4.0 the Apple-signed identity changes the code signature, so Accessibility must be re-approved once after updating.
- Without live status, Perch can only guess from transcripts when an agent is waiting, so status may lag.
- Headless runs (claude -p, codex exec) are not listed, though pi -p and opencode run sessions are.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Perch This agent | 64 · Some gaps | Desktop appFree | ★ 21 | today | Swift | Codex · Claude Code |
| Agent Sessions | 75 · Good | Desktop appFree | ★ 907 | today | Swift | Codex · Claude Code |
| MonoCode | 56 · Major gaps | Desktop appFree | ★ 3.2k | today | TypeScript | Codex · Claude Code |
| Calyx | 59 · Major gaps | Desktop appFree | ★ 349 | 1d ago | Swift | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
README and SECURITY.md enumerate Accessibility, Automation, file reads and the local socket with purpose and consequence of absence, so data_flow_transparency scores 3; network use is limited to Sparkle updates and user-initiated feedback, so external_effects is 2. However permissions are broad (Accessibility can type, Automation can switch terminals) and mitigated only by documentation, so least_privilege is 2; allow/deny and replies require explicit user keypresses, user_confirmation 2; sensitive data handling rests on a local-only claim without encryption or redaction detail, 2; dependency security shows only npm ci and Sparkle EdDSA signing with no audit or lockfile discussion, 1; rollback has *.before-perch backups and live-status removal but no version rollback path, 2; source attribution credits Raycast, Thinking Orbs and Inter, 2.
Architecture description (pure PerchCore, web view renders snapshot only) is self-consistent, 2; dependency availability mentions Xcode 26, Node 20+ and npm without pinning or offline build notes, 1; troubleshooting gives concrete --dump and permission-reset steps, failure_messages 2.
Audience and scenarios across multiple agents and terminals are well described, 3; capability boundaries state supported agents/terminals and headless exclusions but are scattered, 2; trigger precision depends on optional live status and otherwise 'can only guess', 2; environment fit is macOS 15+ Apple silicon only, a hard constraint, 1.
Information architecture is clear (features, install, shortcuts, privacy, development, troubleshooting), 2; install notes cover download and source build, 3; naming stability has no versioned API or naming convention, 1; examples and FAQ include a GIF, design.html and troubleshooting but no formal FAQ, 2; known limitations appear in troubleshooting, 2; MIT license is complete, 3; no CHANGELOG or versioning policy, 1; maintenance responsibility points to a single maintainer and feedback channel, 2.
Output usability (notch card, shortcuts, session jump) is concrete, 2; marginal value is aggregating multi-agent status but assumes several agents installed, 2; cost benefit is free and local at the cost of Accessibility permission, 2.
Claims are largely README self-assertions without traceable test or release evidence links, claim_traceability 1; cross-source corroboration is limited to partial README/SECURITY.md agreement, 1; fact and inference separation is decent (explicit 'can only guess' status), 2.
- Requires Accessibility and Automation permissions that can type and switch terminals; the permission surface is broad and should be granted cautiously.
- Dependency security shows only npm ci and Sparkle signing, with no audit or lockfile discussion.
- Supports only macOS 15+ on Apple silicon, limiting environment fit.
- No CHANGELOG or versioning policy, so update and rollback paths are unclear.
- Publisher identity is unverified by FollowAgents and treated as unknown.