CLI agents

If you already use Claude Code or Codex, you can run them inside Perch. Pick one in the model picker, give it a folder, and it works there with its own tools, under your own login. Your Perch chats and your agents sit in one sidebar, so you can follow all of them from one place.

Each agent works in its own copy of your repo, on a branch of its own, so several can work at once without touching your checkout. When one is done, you see what it changed and merge it into your folder in one click, or open a pull request.

Before you start

• Perch Desktop 2.5.4 or newer, signed in to a Pro or Ultra account. CLI agents are not in Perch on the web.
• Claude Code or Codex installed on this computer and signed in. If claude or codex runs in your terminal, Perch can start it. Perch uses your install and your login, and does not ship either one.
• Git. On Windows, install Git for Windows. Merging needs git 2.40 or newer.
• A folder you added to Perch that is in a git repository with at least one commit, so the agent can have its own copy.

Start an agent

The chat's bar shows what the agent is doing, its name, the folder, and its branch, such as agent/add-a-dark-mode-toggle-t-7q2m.

A chat stays on the agent it started with. To go back to Perch's own models, start a new chat.

While it works

• Approvals come to you. When the agent asks permission for something, a card reads Claude asks to go ahead with the choices it offers.
• Mode sets the agent's own modes, the same ones it has in its CLI, such as Accept edits for Claude.
• Send follow-ups at any time. While it works, what you send waits and goes when the turn ends. You can attach PNG, JPEG, GIF, or WebP images up to 5 MB each.
• Diff opens the Changes panel with every file the agent has changed in its copy.
• Open terminal opens a terminal beside the chat, in the agent's copy of the repo.
• Run several at once. Up to four agents can run at the same time, each in its own copy. The sidebar shows which ones are working.

Its own copy of your repo

By default each agent works in a git worktree: a second checkout of your repo, in its own folder, on its own branch. Your folder, its branch, and anything you have not committed stay as they are while the agent works, and two agents never edit the same files.

A worktree only has the files git tracks. Perch also brings over what most projects need to run:

• Local config files. .env and .env.* files, at any depth, are copied in when git ignores them. To copy other ignored files, such as local settings or certificates, list them in a .worktreeinclude file at the repo root, in .gitignore syntax. A file is only copied if git ignores it in the copy too, so it never ends up in a commit. Up to 200 files, 10 MB each and 50 MB in all. Symlinks are skipped.
• Copy node_modules, under Options on macOS, clones your node_modules into the copy. It is a copy-on-write clone: near-instant, with no extra disk space.
• Setup command, under Options, runs a command such as npm install in the copy before the agent starts, in your shell (PowerShell on Windows). Perch remembers it for the repo. If it fails, or runs past 15 minutes, the agent starts anyway and the chat says so. Setup log in the chat's bar shows its output.

Options also has the Worktree folder, where the copies are made, and the Account folder: if you have several Claude Code or Codex logins, pick the folder of the one to use. Both have to be inside your home folder.

Turn Worktree off to have the agent work in your folder itself. Its changes then land in your folder as it makes them, and there is no diff or merge step.

Bring the work back

When a turn changes files, a card under the conversation says so, for example: "Claude changed 4 files in its own copy of perch-app. They're not in your folder yet." The chat's bar keeps a count until you bring them back. Review changes opens the diff.

Merge into your branch

Merge into main, named after the branch your folder is on, puts all of the agent's changes on your branch as one commit. The commit message starts as the chat's title, and you can edit it. Afterwards, Remove the copy deletes the agent's worktree and branch.

Perch never stashes, resets, or overwrites anything in your folder to merge. It stops and tells you instead when:

• Your folder has changes that aren't committed. Commit them first, then merge.
• The same files changed on your branch and in the agent's copy. Ask Claude to fix sends the agent a message to sort it out in its copy. When it is done, merge again.
• Your folder isn't on a branch, or git is older than 2.40.

Other ways to finish

The menu beside the merge button has two more:

• Commit only commits the changes on the agent's own branch. Your folder doesn't change.
• Open pull request pushes the agent's branch to origin and opens a pull request. With the GitHub CLI (gh) installed, Perch opens it for you. Without it, Perch opens GitHub's page for a new pull request. For other git hosts it pushes the branch, and you open the pull request there.

Closing a chat

If you close a chat whose copy still has changes that aren't in your folder, Perch asks first: Merge first, Keep the copy (its worktree and branch stay where they are), or Discard (deletes the copy and its branch, changes included).

Your own plan

CLI agents run under your own Claude Code or Codex login, so their usage counts toward that plan, not toward your Perch usage. Messages to them don't use your Perch allowance.

Perch shows each agent's own limits as it reports them, the 5-hour limit and the Weekly limit, with when each one resets. You'll find them on the agent's card in the model picker and in Settings › Usage under On this computer, and a note above the message box warns you when an agent is close to its limit. They appear after the agent's first reply on this computer.

Privacy

• Chats stay on this computer. CLI agent chats are not saved to your Perch account, so they don't appear in Perch on the web or on your phone.
• The agent talks to its own service. Your messages go from Claude Code to Anthropic, or from Codex to OpenAI, the same way they do when you use the CLI yourself. They don't pass through Perch's servers.
• Each agent gets only what it needs. Perch starts it with a short list of your environment variables: no other agent's keys and nothing of Perch's.

With sub-sessions

Perch can hand part of a job to Claude Code or Codex. Ask for it, for example "have Codex fix the flaky test in its own session", and Perch suggests a sub-session that runs on that agent, in a new worktree of the chat's folder. Like any sub-session, it starts only when you select Start, and it reports back to the chat that started it. The agent's approvals still come to you.

Troubleshooting

I don't see On this computer in the model picker. Check that you're signed in to a Pro or Ultra account in Perch Desktop 2.5.4 or newer.

An agent says Not installed. Install it so claude or codex is on your PATH, then quit and reopen Perch.

It says Needs sign-in. Select Sign in in a terminal, which runs claude or codex login for you. Finish signing in, then select Try again.

It says its CLI is older than Perch needs. Update it. For Claude Code, run claude update. Update Codex the way you installed it, with npm or Homebrew.

It says it needs Node 22. That message comes from desktop builds before 2.5.4. Update Perch Desktop, which runs the agents without Node.

The folder can't have a worktree. It has to be in a git repository with at least one commit. You can also turn Worktree off.

On Windows, the copy can't be removed. A file in it is open in another program. Close it, then try again.