Perch
Guide contents

Field guidePreferences and shortcuts

Configuration file (config.toml)

Edit config.toml to change where Perch finds your repositories, which agents it runs, and how the app looks. Every setting is optional.

Repositories and local roots

Perch reads ~/.perch/config.toml (or $PERCH_HOME/config.toml). A repository entry can name a GitHub repository, a local clone, or both.

poll_interval_secs = 60

[[repo]]
github = "slatedb/slatedb"
name = "slatedb"
root = "~/Code/slatedb"

Set name for the sidebar label and root to the path of your clone. Perch scans that clone for local branches and worktrees. Scanning leaves GitHub history alone. A worktree without a PR appears under Authored. Once it has a PR, the PR author determines where it appears. The base branch has no row. A local-only repository appears as local/<name> and supports worktrees and agents.

To keep a discovered worktree out of the sidebar, choose Hide. Find it under Recent and choose Unhide to bring it back. Deleting its row only hides it until the next scan because Perch leaves the checkout on disk.

If you rename a branch with git branch -m, Perch uses Git’s reflog to keep its threads, runs, and hidden state together. Switching branches, renaming onto a branch with its own row, or renaming a branch attached to a PR leaves the history with the old row.

Work, language servers, and appearance

Use [work] for new worktree defaults and [repo.work] for permissions on a particular repository.

[work]
branch_prefix = "chris/"       # before a branch name Perch fills in
approvals = "auto"             # or "ask"; see Approvals

[[repo]]
root = "~/Code/perch"

[repo.work]                    # what a Work run here may reach
approvals = "never"            # over [work]'s, for this repository only
write = ["~/.cargo/registry", "~/.cargo/git", "~/.cargo/.package-cache"]
network = ["index.crates.io", "static.crates.io"]
trust = false                  # true loads the repository's own agent config

The write and network lists start empty. Grant write access to the specific cache directories an agent needs. For example, granting the whole ~/.cargo directory would also let it change your Cargo configuration and binaries. Perch skips entries that include your home directory or ~/.perch, and paths in or containing a configured root’s .git directory. It reports skipped entries at startup.

When you leave an item, Perch keeps up to two idle language servers for ten minutes so you can return without waiting for the workspace to load. Set the combined memory budget under [lsp].

[lsp]
max_memory_mb = 8192           # the default

Over budget, Perch stops the oldest idle server first. Servers for open views can use more than the budget on their own.

Use [display] to change the size of the interface. Restart Perch to see the change.

[display]
zoom = 1.0                     # the default; 0.75 to 2.0
code_font_size = 12            # the default; 8 to 32

zoom scales the whole window. For example, 1.25 makes text, icons, and spacing 25% larger. code_font_size sets the editor text size before zoom, including headers, hovers, and references. Comments and agent replies follow the window zoom.

Use [ui] for the theme, light or dark appearance, and code font.

[ui]
appearance = "dark"            # "light", "dark" or "system", the default
theme = "warm-linen"           # "classic", "warm-linen" or "blue-mist"
code_font = "Fira Code"        # off macOS only

Choose a theme in Settings → Appearance to preview and apply its palette. Each theme has a light and a dark version. Perch starts with Warm Linen in a fresh Perch home and uses Perch Classic when theme is absent.

By default, Perch follows the system appearance. On Linux under X11 it starts light because X11 does not supply the setting. Choosing light or dark applies immediately. Choosing "system" applies the current system appearance immediately. Restart Perch to follow subsequent system changes.

On macOS, the code font is SF Mono. On Linux, set code_font and restart. Otherwise Perch uses the first installed font from JetBrains Mono, DejaVu Sans Mono, Noto Sans Mono, Liberation Mono, Adwaita Mono, and Droid Sans Mono.

Loading a Rust or Java project can run code from the checkout. rust-analyzer runs build scripts and proc macros and reads .cargo/config.toml and rust-toolchain.toml. jdtls can run Gradle or Maven. On your own work in a configured repository, Perch starts these servers automatically. That includes branches in your local root, even if you checked one out from a fork, the default branch for an issue, and your PRs from the configured repository or your fork.

On another person’s PR, a branch created from it, or an unconfigured repository, Perch asks first. Choose Trust and start to trust this item, including future commits pushed to it. Deleting the item clears that decision. Branches you created from PRs before upgrading may ask once.

To trust one server throughout a repository, select its Always trust checkbox when you confirm. The Worktree row also offers Trust and Start, Always Trust, and Stop Trusting. Revoking repository trust stops that server on items with no other trust decision. Go and TypeScript servers can start without this prompt. To allow all language servers across a repository, including other people’s PRs, use the following setting.

[[repo]]
github = "slatedb/slatedb"

[repo.lsp]
trust = true                   # false, the default, asks as above

~/.perch contains the database, avatars, managed clones, worktrees, and agent state. The database includes local conversations and review drafts. GitHub can supply fresh notifications, but it has no copy of those local records.

Database upgrades keep conversations, agent attempts, session IDs, and activity history. If an upgrade fails, the original database stays in place. Perch refuses to open a newer or unsupported format.

All config.toml keys

Settings changes only the keys you edit and preserves comments. Most edits apply within seconds. Restart the app for [display] or [ui] code_font changes, and restart the engine for worktrees_dir. Edit the file directly to change token, worktrees_dir, or an existing repository’s github and root.

KeyDefaultWhat it does
tokennoneGitHub token to use if the process environment and gh provide none. Perch checks again if the token is missing or GitHub rejects it.
poll_interval_secs60Shortest time between inbox polls; GitHub can ask for longer
github_hostnoneA GitHub Enterprise host whose remotes count as GitHub
[agent] binary"claude"Claude Code executable, a name on PATH or a path
[agent] model"opus"Model the composer's picker starts on
[agent] effort"high"Claude Code's default effort: low, medium, high, xhigh, max or ultra
[agent] models["fable", "opus", "sonnet", "haiku"]Claude models the picker offers
[agent] max_concurrent_runs4Maximum simultaneous Claude Code runs. Other Claude runs wait.
[agent] sandboxtrueRun Claude Code commands in its sandbox. See Without the agent sandbox.
[agent.codex] binary"codex"Codex executable, a name on PATH or a path
[agent.codex] effort"high"Codex's default effort
[agent.codex] modelsCodex's own listCodex models the picker offers
[agent.codex] max_concurrent_runs4Maximum simultaneous Codex runs
[agent.codex] sandboxtrueRun Codex commands in its sandbox (read-only / workspace-write). Off uses danger-full-access.
[agent.gemini] binary"agy"Antigravity CLI executable, a name on PATH or a path
[agent.gemini] effort"high"Gemini's default effort
[agent.gemini] modelsagy's own listGemini models the picker offers
[agent.gemini] max_concurrent_runs1Maximum simultaneous Gemini (agy) runs
[agent.gemini] sandboxtrueRun Gemini (agy) print-mode commands in its terminal sandbox. See Without the agent sandbox.
[agent.opencode] binary"opencode"OpenCode 2.3.0+ executable, a name on PATH or a path
[agent.opencode] effort"high"OpenCode's default effort
[agent.opencode] modelsOpenCode's own listProvider-qualified IDs from opencode models
[agent.opencode] max_concurrent_runs4Maximum simultaneous OpenCode runs
[work] branch_prefix""Put before branch names Perch fills in, such as "chris/"
[work] approvals"auto"Who answers a Work run's requests outside its sandbox: "auto" (the CLI's auto-reviewer, then you) or "ask" (you)
[work] approval_timeout_mins15 in the app, 480 under perchdMinutes a request to you waits before it is denied
[keybindings] actionthe action's keysKeys for an action by its id: a string such as "super+t", a list of them, or "" for none; see Keyboard shortcuts
[ui] appearance"system""light", "dark" or "system"
[ui] theme"classic""classic", "warm-linen" or "blue-mist". A fresh Perch home starts with "warm-linen".
[ui] code_fontnoneCode font off macOS; on macOS code is always SF Mono; applies after a restart
[display] zoom1.0Scales the whole window, 0.75 to 2.0; applies after a restart
[display] code_font_size12Code font size before zoom, 8 to 32; applies after a restart
clone_root~Directory on the SSH host for repositories you add by name, such as "~/Code"
worktrees_dir$PERCH_HOME/worktrees (normally ~/.perch/worktrees)Base directory for new Perch-managed branch worktrees. Applies after an engine restart.
[remote] hostnoneSSH host to use when there is no saved window session (for example "chris@devbox:2222"). Perch subsequently reopens each window in its last environment.
[remote] commandnoneCustom engine command for the host’s login shell, such as "perchd bridge". By default the app uploads and starts its bundled engine.
[lsp] max_memory_mb8192Combined memory budget for language servers. Perch stops idle servers first.
[[knowledge]] dirrequired per entryExternal directory relative to $PERCH_HOME/knowledge/
[[knowledge]] reposevery repositoryRepositories whose agents may read this directory
[[repo]] githubnoneThe repository's owner/repo on GitHub; leave out for a local-only repository
[[repo]] namethe repo's nameName shown in the sidebar
[[repo]] rootnonePath to your local clone, where Perch finds branches and creates worktrees
[[repo]] basethe remote's defaultBase branch, when the remote doesn't say
[[repo]] sync_historyfalseKeep the repository's GitHub issues, pull requests and discussions available to agents
[repo.work] write[]Extra directories Work runs may write, such as a package cache
[repo.work] network[]Hosts Work runs may reach, such as index.crates.io
[repo.work] approvals[work] approvalsOverrides it for this repository; also takes "never", which allows every request
[repo.work] trustfalseLoad the repository's own .claude/, .mcp.json, .codex/ and .agents/ config for Work runs
[repo.lsp] trustfalseStart rust-analyzer and jdtls on anything in this repository without asking

The reference covers what each setting does in more detail.

Worktree directory

Add worktrees_dir as a top-level key in config.toml on the machine running the engine, then restart the engine.

worktrees_dir = "~/.herdr/worktrees"

~ expands to the engine user’s home. Relative paths start at PERCH_HOME (usually ~/.perch). Changing this setting affects only new worktrees. Existing checkouts stay where they are, and Perch leaves unrelated directories alone.

GitHub history

Turn on Sync GitHub history in a GitHub repository's card under Settings → Repositories, or set sync_history = true in its [[repo]] entry on the engine's machine.

[[repo]]
github = "slatedb/slatedb"
root = "~/Code/slatedb"
sync_history = true

The engine downloads open and closed issues, PRs, and their discussions into the repository archive. It refreshes at startup and about once an hour while the engine runs. You can close the desktop app while a remote engine continues syncing.

External knowledge

Add directories in Settings → Knowledge or in the engine's config.toml.

[[knowledge]]
dir = "discord/slatedb"
repos = ["slatedb/slatedb", "slatedb/slatedb-go"]

[[knowledge]]
dir = "notes"

List GitHub repositories as owner/repo or local repositories as local/<name>. Names are case-insensitive. Omit repos to share the directory with every repository, or use an empty list to share it with none. In Settings, turning off All repositories starts with an empty list.

Put Markdown on the machine running the engine. An optional INDEX.md gives agents a starting point. Links to original messages or documents let them check a source. Use regular files and directories without symlinks or instruction files such as AGENTS.md, CLAUDE.md, or GEMINI.md. Perch reserves the top-level names perch and reviews.

Start a new Ask, Work, or Review session to use a newly shared directory. Perch treats its contents as untrusted reference material. You or the tool that supplies the files must keep them up to date.

Settings explains why a directory was skipped. Common reasons include a missing folder, a symlink or agent instruction file anywhere inside, more than 200,000 entries, or an agent that cannot accept the directory. The engine logs changes and caches each check for up to a minute. After a fix, try a new run once that minute has passed.

OpenCode

In Settings → Agents → OpenCode, check that Perch found the executable on the machine with your checkout. Leave Models empty to use OpenCode’s catalog, or enter the models you want in the picker.

OpenCode settings with the detected executable and an empty Models field using OpenCode’s catalog

Sign in on that machine with the command below, then restart Perch to refresh the picker. Perch uses its own OpenCode profile so an “always allow” decision from your terminal can’t approve a command in Perch.

perch_home="${PERCH_HOME:-$HOME/.perch}"
OPENCODE_DB="$perch_home/opencode/opencode.db" OPENCODE_CONFIG_DIR="$perch_home/opencode/config" opencode auth login --standalone

Custom provider configuration goes in $perch_home/opencode/config/opencode.json. OpenCode Zen also accepts OPENCODE_API_KEY in the engine's environment.

Ask and Review have read and search tools. Work allows worktree edits and sends shell commands through Perch's approval controls. Perch disables project configuration, plugins and MCP servers for these sessions. When the model offers the selected effort variant, Perch uses it. Otherwise OpenCode uses the model's default.

Environment variables and settings on an SSH host

PERCH_HOME contains the cache and logs. Only one engine can use a home at a time. If another engine owns the directory, Perch reports its process ID. Each engine reads config.toml on the machine where it runs.

PERCH_SSH selects the SSH program the desktop app uses for connections, engine uploads, and remote terminals. For example, it can name a wrapper that supplies -F <config>.

Set PERCH_IDLE_EXIT_SECS in the host’s login environment to change how long the app-started engine waits with no clients or active or queued agent runs. The default is 900 seconds.

In a remote environment, [ui], [display], [keybindings], and [remote] belong to the desktop app and use its local file. The engine reads all other settings from the host. Settings saves each change on the appropriate machine. Adding a repository or fixing the host’s token triggers the host checks again.