Guides
Get started with Perch on your Mac
Updated · 2 min read
Perch sits beside the coding agents you already use. Start with monitoring one session, check that its activity appears, then decide whether you want to answer supported requests from the shelf.
Check availability and requirements first
The current offer is for Apple silicon Macs running macOS 14 or later. Perch is built with SwiftUI and AppKit. Intel Macs are not included in the current offer.
Purchases are closed until delivery is ready. Join the launch list on the home page for availability; this guide describes the setup workflow for a Perch build you already have. No download or delivery date is promised here.
Connect your first agent
- Open Perch and use its setup flow or agent settings to see the detected agents.
- Review the exact change proposed for the agent’s settings before connecting.
- Connect the agent. Perch makes a backup and adds its own hook entries while preserving existing settings.
- Start a new session after connecting so it can pick up the hooks.
- Run a small task and confirm activity and the end of a turn appear in Perch.
Read the three states
The shelf groups sessions into Needs you, Working and Recent. Events differ by provider: Cursor passive hooks do not expose awaiting-permission status. A state display cannot show an event the integration never receives.
- Blue ring: the session is working.
- Amber dot: a supported event says the session needs you.
- Green check: a turn has finished. Review the result in the project.
Choose whether to enable answering
Answering is off by default. Turn it on in Settings only if you want supported requests handled in Perch. Claude Code supports approvals, questions, plans and replies. Codex supports approvals and replies. Cursor supports replies after a turn.
Every answer waits two seconds so you can undo it. If the session’s app is already in front, Perch steps aside and the agent asks there.
Remove or repair the connection
Remove in agent settings takes out Perch’s own entries. If its hooks go stale or the app moves, use Repair when Perch offers it. Avoid replacing the agent’s entire settings file as a troubleshooting shortcut.
Common questions
Do I need a Perch account?
No. The app has no account or server and makes no network requests.
Do I need to grant screen recording or Accessibility?
No. Optional exact-tab jumping may ask for Automation permission for Terminal or iTerm2.
Your agents, one glance away.
Perch is launching soon. Join the launch list to hear when it is ready.
macOS 14+ · Apple silicon · Native SwiftUI + AppKit