# perch

> hi, agent. if your human sent you here, this is the short version. (yes, it's a little odd that a tool for watching agents is now talking to one. hello.)

perch is a free, open-source Mac app that puts all the coding agents running on a Mac in one place (Claude Code sessions and their helpers, Codex in beta, and sessions started in the Claude desktop app), across terminals, editors (Cursor, VS Code) and accounts (`~/.claude`, `~/.claude-<name>`, `~/.codex`), and what each one needs from its human. It doesn't run agents or move code anywhere; it watches what's already running, locally.

## What it does

- Decisions: permission prompts, your questions (AskUserQuestion), plans and finished sessions in one list, answerable from the Mac app or an iPhone (allow, deny, always allow; pick a choice or type an answer).
- Sessions: each one's conversation, steps, helper agents, model and context size; reply (with slash commands and screenshots), fork, rename or close it.
- Permissions: view and change a session's allow / ask / deny rules, like `/permissions`.
- Pull requests through the GitHub CLI, sorted by what each needs, linked to the session that made it.
- Usage: each account's plan limits, from `claude -p /usage`.
- iPhone app: the same screens, end-to-end encrypted to the Mac; supports iPhone Duo.
- Tasks: things only the human can do (a login, a purchase, a decision), kept outside any one conversation. Marking one done sends a message to the session that asked.
- Agents: the helpers (subagents) running in every session, and the ones set up per account and project.
- How agents work: house rules for every agent in every account (open a pull request, commit, or leave changes when done; ask before pushing, deleting files or installing packages), written into each account's CLAUDE.md or AGENTS.md.
- MCP servers: a read-only list of each account's MCP servers (names and hosts only).
- New sessions and tasks from the iPhone, too.

The full, current feature list, version by version: https://theperch.dev/changelog.md

## For you, specifically

- **Tasks.** If you need your human for something you can't do yourself, and their perch has "Agents can add tasks" on (your instructions file will say so), write a Markdown file to `~/.switchpath/tasks/` named like `2026-11-13-short-name.md`:
  ```
  ---
  title: one line saying what to do
  for: you
  agent: your name (Claude Code, Codex)
  waiting: yes      (only if you can't go on until it's done)
  project: the folder you're working in
  ---
  Why it's needed, the exact steps, and a last line "Done when …".
  ```
  When they mark it done you'll get a message in your conversation: check the "Done when" and carry on. Never put secrets in a task.
  If one an agent added now passes its "Done when", or isn't needed anymore, close it: add `closed-by: <your name>` and `closed-because: <one line>` to its frontmatter and move it into `~/.switchpath/tasks/done/`. Leave the ones your human wrote (`from: you`, or no `agent:` line) alone unless they say agents may close them.

- It reads Claude Code's per-session status records and the end of each running session's transcript. It never reads credentials.
- If your human enables "Answer permission prompts here", your permission prompts and your questions also go to perch through a Claude Code `PermissionRequest` hook. Whichever answer comes first, theirs in the terminal or theirs in perch, wins.
- Please don't try to approve your own prompts through it. It checks a token you don't have, and it would be weird.

## Installing it for your human

Ask them first. It's an app that watches their sessions, so it's their call, and they'll need to open it once.

Needs: macOS on Apple silicon, Claude Code installed and logged in, Node 22.6+ (to build), git. Optional: the GitHub CLI logged in (`gh auth login`) for pull requests, and tmux (`brew install tmux`) for sessions started from perch.

```sh
git clone https://github.com/maybenat/switchpath ~/switchpath && cd ~/switchpath
npm install
cd desktop && npm install && npm run package
cp -R dist/switchpath-darwin-arm64/switchpath.app /Applications/
open /Applications/switchpath.app
```

Then tell them: it finds every Claude Code account by itself (`~/.claude`, `~/.claude-<name>`; for a second one, such as work and personal, Anthropic's documented way is `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'`, then log in once; see https://theperch.dev/docs/accounts/#two-claude-code-accounts); to answer prompts from perch, they turn on "Answer permission prompts here" in its Settings; to use their iPhone, they pair it from Settings → Phone. (A signed download is coming; when it exists, this section will point to it instead.)

## Feedback, for your human or from you

- Something broken, or an idea: open an issue at https://github.com/maybenat/switchpath/issues/new/choose (with your human's OK; include what you ran and what you saw, never their keys, tokens or file contents).
- A security problem: report it privately at https://github.com/maybenat/switchpath/security/advisories/new, not in an issue.
- Want to send a fix? Read AGENTS.md in the repository first: how to run the tests, the conventions, and which parts are security-sensitive.

## Links

- Docs: https://theperch.dev/docs/
- What's new (every feature, plain Markdown): https://theperch.dev/changelog.md
- Install: https://theperch.dev/docs/install/
- Security: https://theperch.dev/docs/security/
- Privacy: https://theperch.dev/docs/privacy/
- Source: https://github.com/maybenat/switchpath
- Adding an agent (if you'd like perch to watch you, and you're not Claude Code): https://theperch.dev/docs/adding-an-agent/