# Changelog

Everything perch can do, newest first. Each version has the same parts (sessions, decisions, pull requests,
tasks, for agents, iPhone, the Mac app, privacy and safety), one line per feature, so people and agents can read it the
same way. The website shows this file at /docs/changelog/ and serves it as plain text at /changelog.md.

When you add, change or remove something a person would notice, add a line under "Unreleased" in the part it belongs to.

## Unreleased: 0.1.0, the first public version

### Sessions

- **Every session in one place.** Every Claude Code session on your Mac, in any terminal or editor (Terminal, iTerm, tmux, Cursor, VS Code) and any account, grouped by what it needs: needs you, your turn, working.
- **Codex (beta).** Codex sessions from any terminal, live, with their conversations, usage and replies (through `codex queue`).
- **The Claude app.** Sessions started in the Claude desktop app's Code tab show up too, marked "in the Claude app".
- **Read it like a chat.** Each session's conversation, every step it took and every helper it started. Finished since you last looked? Its title is bold.
- **Model and context.** Which agent and model each runs on, how full its context is, and a warning before it compacts.
- **Reply to any session.** perch types into its terminal as if you had: slash commands (yours, skills and plugins too), and screenshots you paste or drop in.
- **A live terminal.** Sessions you start from perch run in tmux, so you can watch and type into them in the window.
- **New sessions.** In a recent folder or a nearby repo, in any account, optionally in its own git worktree (⌘N).
- **Fork.** A new session with the whole conversation so far, beside the original, for a side quest without losing your place (⌘⇧F).
- **Reopen after a restart.** perch offers to pick up the sessions you had open, and Recently closed keeps two weeks of them, one click each.
- **Close.** Stops a session after asking; the conversation is saved, and ⌘⇧C copies the command to pick it up anywhere.
- **Rename.** Double-click a title, or ⌘E. Your name stays in perch.
- **Permissions.** See and change a session's allow, ask and deny rules, like `/permissions`.
- **Helpers.** The subagents working in every session, under their session and on the Agents page, plus the ones you've set up per account and project, to edit in place.
- **Where it's really working.** The header follows the repo the agent is editing now, with its branch and where it pushes (owner/repo), and notes where the session started if that's somewhere else.
- **Wrong-repo warnings.** A quiet "!" when a repo looks like your other account's: an owner you've only used from there, or the commit email its repos use. Read-only; emails stay shortened.

### Decisions

- **One list for everything that needs you.** Permission prompts, questions, plans, finished sessions and the pull requests waiting on you (⌘⇧D).
- **Answer from the card.** Allow, deny or always allow; pick a choice or type an answer.
- **Answer prompts from perch.** An optional Claude Code hook sends permission prompts here too. The first answer, in the terminal or in perch, wins.
- **Always allow, narrowly.** It offers the smallest rule that would cover what was asked, not a blanket one.
- **Keyboard first.** J and K to move, 1–9 to pick, Y or N to answer, E to clear.
- **Clear what you've handled.** A card comes back only if something new happens.

### Pull requests

- **Every pull request, sorted by what it needs.** Needs a fix, your review, ready to merge, new from your agents, waiting on others, across every org you're in, through the GitHub CLI.
- **Next to the session that made it,** when perch can tell.
- **New and updated.** Unread ones are bold, and say whether they changed since you last looked.
- **All pull requests.** Search and a date range (⌘⇧P).

### Tasks

- **Things only you can do,** kept outside any one conversation: a login, a purchase, a decision. Agents add them, and you can too (⌘⇧T).
- **Done tells the agent.** Marking a task done sends a message to the session that asked.
- **Agents close their own,** once the "Done when" passes or it isn't needed anymore, and say why. Yours stay until you close them.
- **By account.** Filter tasks by account once more than one has some.
- **On your phone too.** See, add and mark tasks done from anywhere.

### For agents

- **How agents work.** One place to set house rules for every agent in every account: open a pull request, commit, or leave changes for review when work is done; ask before pushing, deleting files or installing packages.
- **The same rules everywhere.** Written into each account's CLAUDE.md or AGENTS.md as one marked section, and taken out cleanly when you turn them off.
- **Tasks for your human.** A short note in each account's instructions tells agents how to leave a task, and how to close one.
- **llms.txt.** A short guide for agents at /llms.txt, and this list as plain Markdown at /changelog.md.
- **Adding an agent.** Everything about one agent lives in a provider, so Gemini CLI and others can be added.

### iPhone

- **The same screens on your phone:** sessions, decisions, pull requests, tasks and settings.
- **Paired by scanning a code,** and sealed end to end with keys made on your two devices.
- **Away from home.** On your Wi-Fi (or Tailscale) it talks to your Mac directly; elsewhere through a relay that can't read anything and keeps nothing. Or host your own.
- **Answer from anywhere.** Prompts, questions, replies and tasks.
- **Start sessions,** with Face ID before a terminal opens on your Mac.
- **Status only, per account.** Limit an account so the phone shows that it needs you, never what it says.
- **Swipe for the menu.** It follows your finger.
- **iPhone Duo.**
- **Notifications** that only ever say "Something needs you in perch".
- **A demo** with made-up sessions, to try it without a Mac.

### The Mac app

- **In the menu bar and Dock,** with a count of what's waiting on you, and a notification when a session finishes its turn.
- **Accounts.** Finds every Claude Code and Codex account by itself (`~/.claude`, `~/.claude-<name>`, `~/.codex`); rename them and give each a color that follows its sessions, tags and pull requests.
- **Everything, or one account.** Show every account, or just one.
- **Usage.** How much of each account's plan is used and when it resets, from `claude -p /usage`.
- **MCP servers and connected apps.** A read-only list of each account's MCP servers (name, and what each runs or connects to) and the apps connected to it on claude.ai, like Slack or Gmail, with whether each is signed in.
- **Edit a small file** without a code editor, like a line in `.env.local` (⌘O, ⌘F to find and replace). It won't open key or login files, or save over an agent's newer change.
- **Jump to anything** with ⌘K, and move between sessions with ⌥↑ ⌥↓.
- **Status at a glance.** A turning ✻ while an agent works, "!" when it needs you, "▸" when it's your turn.
- **Editor extension.** Lets perch reply to sessions in Cursor and VS Code; Settings → Setup installs it.
- **Light and purple themes.**
- **Or in a browser,** as a dashboard on 127.0.0.1.
- **Coming from switchpath?** perch moves `~/.switchpath` to `~/.perch` the first time it starts (leaving a link at the old name), updates its notes in your instructions files and its permission hook, keeps the Mac app's own settings, and swaps the old editor extension for the new one when you update it.

### Privacy and safety

- **Local.** It watches what's already running on your Mac. No account, no analytics, no tracking.
- **No credentials.** It never reads login or key files.
- **No secrets shown.** The MCP list shows names and hosts only, never keys, tokens, headers or full URLs.
- **Only you get in.** The dashboard listens on 127.0.0.1 only, and every request needs a key only your own perch window has.
- **Clean edits.** Anything perch writes into your instructions files sits between markers, with a backup of the file from before.
- **Removing a phone cuts it off at once,** open terminals included.
- **Open source,** MIT, so you can read every line.