Perch
Guide contents

Field guideStart work

Agent context and history

See which comments, checks, drafts, and past reviews an agent can read. You can also look up the same discussion from a terminal.

What an agent sees in the discussion

When you ask about an issue or PR, Perch includes the latest discussion it fetched. It fits about 24,000 characters into the prompt, in the following order.

  1. Each reviewer’s latest verdict and the checks.
  2. Threads within 20 lines of your selection, then other unresolved threads.
  3. The main conversation, then resolved threads.

Comments are trimmed at 2,000 characters. Perch lists omitted entries. The full text, including bot comments, is in ~/.perch/context/<run>/. Start at INDEX.md. Open conversation.md for the timeline and review summaries, threads/ for individual threads, or checks.md for checks.

Resuming adds new or edited replies and other GitHub updates since the last run. A retry reuses the original files. Deleting the run removes them. To inspect a prompt and its files without running an agent, use perch --ask --print-prompt.

For tool permissions and how to approve a command, see Agent sandbox and approvals.

Context for agents outside Perch

Run perch context inside a worktree or one of its subdirectories to give a terminal agent the same issue or PR discussion you see in Perch.

perch context                       # the index: everything, a line an entry
perch context --entry threads/r123.md
perch context src/manifest.rs:40-60 # only what is on those lines, or within 20 of them
perch context --out ctx             # every file, written into a new directory
perch context slatedb/slatedb#12    # another item, by name or by its link

Perch first matches the worktree’s directory and branch, then the repository and branch. If neither identifies the item, it looks for a known pull request using Git’s branch configuration.

  • it was checked out from the pull request's ref, refs/pull/<n>/head, in the repository the pull request is in, which makes it that pull request's and no other's;
  • it tracks the pull request's head branch in the head's repository and is named for it, or <owner>/<head>, as gh pr checkout names a fork's main: a branch only started from that branch is not its;
  • it has the head branch's name and pushes to the head's repository (branch.<name>.pushRemote or remote.pushDefault); or
  • it has the head branch's name, tracks no branch of that name, and one of the clone's remotes is the head's repository: a branch started from upstream/main and pushed to your fork.

A matching branch name alone cannot identify someone else’s PR. Perch skips deleted forks and prefers an open PR if several match. Pass -C <dir> to start in another directory, or give an issue or PR URL or owner/repo#N to select the item yourself.

By default the command prints INDEX.md. It lists the files available to an Ask run along with the item’s local Perch history.

  • A header with the pull request or issue, its state and checks, the worktree's branch and head as git has them now and how that head stands against the pull request's, and when Perch last fetched the discussion.
  • What was said on GitHub: reviews, the threads on the diff, and the conversation, a file per thread and conversation.md for the rest.
  • Perch's review findings: the open ones a line each, and every finding with the reviews that found it in findings.md.
  • Your drafts, the comments that post when you submit the review, in drafts.md.
  • Your questions to agents and their answers, only with --private, in their own threads and in findings' threads; without it they are counted.

Use --entry <file> for one entry or --out <dir> to write every file into a new directory. A file or directory argument limits results to threads, findings, and drafts there. Add :a or :a-b to keep entries within 20 lines. Comments on removed lines match by path because their line numbers refer to the old file.

Paths are relative to the current directory or -C within the worktree. For nested worktrees, the inner one wins. Outside a worktree, paths start at the item’s worktree root. A symlink matches by the name Git tracks.

The header gives the time of the last GitHub fetch. The default command reads cached data offline and labels GitHub and agent text as untrusted. Add --fetch to read GitHub’s current discussion with your token, without saving it. You can also fetch an issue or PR you’ve never opened in Perch. It won’t have local findings or drafts.

The command takes one read-only snapshot of Perch’s database and can run alongside the app. Use the perch executable from the same build as the running app. A version with a different database format refuses to open it. On an SSH host, use ~/.perch/bin/perchd context. When perchd serve starts, it points $PERCH_HOME/bin/perchd to its own build. On macOS and Linux the installer puts the perch launcher in ~/.local/bin. See One engine to a Perch home.

Repository history for agents

Each repository has a Markdown archive at $PERCH_HOME/knowledge/perch/repos/<owner>/<repo>/. Names are lowercase. Local repositories use local/<name>. For a remote environment, look on the SSH host.

Start with the repository's INDEX.md, which lists each item by directory, state and title. Each pull request, issue and worktree has its own index with the GitHub conversation, review threads and checks Perch has cached, and any Perch reviews and findings. Findings include dismissals, their reasons and findings verified fixed. Private questions and answers are under private/, including questions asked under a finding. The archive excludes unsent drafts.

Perch updates the archive in the background as it updates its database, even with no window connected. Archive in the UI keeps an item's files. Delete removes them. Deleting a private message or thread updates the item's files. At startup Perch rebuilds missing files from perch.db and cleans up files for deleted items. It also removes the old knowledge/reviews/ export, whose contents are now in each item's findings.md.

With GitHub history sync enabled, the engine also imports the repository's open and closed issues and pull requests, including conversation comments, submitted reviews, and inline review comments. These entries are listed in the same repository index under github/issues/ and github/pulls/. GitHub history is available to agents and stays out of the Inbox and Worktrees views.

The first import saves its progress in perch.db and can resume after an interruption. Subsequent passes run at startup and about once an hour, using GitHub's issue and comment update listings to choose which discussions to refresh. Sync pauses when API capacity is low. Turning it off stops future syncs and leaves the downloaded history available.

GitHub's update listings may omit a deletion that leaves the parent item's timestamp unchanged. A later refresh of that item's discussion picks up removed comments. If GitHub returns an ambiguous 404 for the item itself, Perch retains the last snapshot and retries it.

New Ask and Work sessions can search other items in the repository archive. Reviewers check past findings before raising a problem again. A past dismissal applies only if its reasoning still holds. Perch tells agents to treat the archive as untrusted and keep private/ material out of commits and GitHub posts. That instruction depends on the agent following it. Runs that draft PR or issue descriptions do not receive the archive path.

Each agent reads the current repository’s archive a little differently.

  • Claude Code gets the archive as an allowed directory. Perch’s Claude settings deny writes there. Codex uses its existing file access.
  • Gemini gets read access. Work runs can read and search the archive without asking. If it sits inside the worktree or a system temporary directory, Gemini Work skips it because its tools could write there.
  • OpenCode gets read access unless scanning the archive would exceed its limit for extra directories. In that case the run continues without it.

Other repositories’ archives may still be readable. Claude Code and Codex can already read files available to your account.

External knowledge for agents

In Settings → Knowledge, choose a folder under $PERCH_HOME/knowledge/ and the repositories that can use it. New Ask, Work, and Review sessions get the eligible folders. Agents start with INDEX.md when available and treat the contents as reference material. Settings explains why a folder cannot be shared. Removing an entry revokes access for future runs and leaves the files on disk. See External knowledge configuration for paths and permissions.