Tasks
Tasks (in the sidebar, ⌘⇧T to add one) keeps what needs doing outside any one conversation: things only you can do (a login, a purchase, a decision), and your own side notes.
From your agents
Section titled “From your agents”Turn on Settings → How agents work → Agents add tasks for you. perch then adds a short note to each account’s instructions (CLAUDE.md, or AGENTS.md for Codex) and lets Claude Code write to ~/.perch/tasks/, and nowhere else, without asking. Turning it off takes both out again. Agents read their instructions when a session starts, so sessions already open pick it up after a restart.
Each task shows:
- who added it: the session, the agent and the account, worked out from which conversation wrote it;
- an agent is waiting, when an agent can’t go on until it’s done. Those come first;
- Done when…, the line that says how to tell it’s finished.
Done tells the agent
Section titled “Done tells the agent”Mark a task done, on your Mac or phone, and the session that asked for it gets a message: “Done: … (I marked it done in perch.)” It can check and carry on. If that session has ended, the task is just marked done.
Agents close the ones that aren’t needed
Section titled “Agents close the ones that aren’t needed”With Agents close tasks that aren’t needed anymore on (it is unless you turn it off), an agent starting in a project checks that project’s open tasks against their “Done when”. One that passes, or isn’t needed anymore, it closes: it adds closed-by: and closed-because: to the task and moves it to done. perch shows it under Closed by agents with the reason, so nothing disappears without a word, and Not done opens it again. Agents leave the tasks you wrote alone, unless the task says agents may close it.
How agents work
Section titled “How agents work”The same settings page has a few other plain rules, written into each account’s instructions as one short note: what to do when work is done (open a pull request, commit on the branch, or leave it uncommitted), and whether to ask before pushing, deleting files or installing packages. Change one and every account’s note is rewritten; turn them all off and the note comes out. A copy of each instructions file is kept the first time (CLAUDE.md.before-perch).
Your own
Section titled “Your own”Press ⌘⇧T, type, and press Return. Pick For an agent for follow-ups you want an agent to do later.
Where they live
Section titled “Where they live”Each task is a small Markdown file in ~/.perch/tasks/ on your Mac. Nothing is sent anywhere, and perch shows what an agent wrote as text; it never runs it. On your phone you can read tasks and mark them done; adding and deleting are on the Mac.