The agent harness
Perch runs a full agent harness on Desktop and CLI: shell, search, file editing, background jobs, a sealed sandbox, plan mode, and risk-tiered permissions. Here is the complete toolset and the controls that govern it.
Underneath the document work and the audits, Perch is a general agent harness. It runs commands, searches and edits files, spawns helpers, and executes code in a sandbox. The same machinery that reconciles a ledger will refactor a module, because it is the same machinery.
This page is the reference for what Perch can actually do on your machine, and the controls that decide how much of it happens without asking you first.
Desktop and CLI only
Shell and search
| Tool | What it does |
|---|---|
bash | Runs shell commands in the workspace. |
grep | Searches file contents across the folder. |
glob | Finds files by pattern. |
Search runs as real grep and glob rather than as a semantic guess, so finding every call site means finding every call site.
Reading and writing files
| Tool | What it does |
|---|---|
readLocalFile | Reads a file into context. |
writeLocalFile | Writes a file. |
editLocalFile | Edits part of a file in place. |
moveLocalFile, copyLocalFile | Moves or copies. |
createDirectory, deleteLocalFile | Creates directories, removes files. |
statPath | Inspects a path without reading it. |
Every call is validated against the approved roots for your workspace, so Perch cannot reach outside the folder you opened.
Background jobs
Long work does not have to block the conversation. Perch can start a command in the background and keep going.
| Tool | What it does |
|---|---|
run_in_background | Starts a command as a detached job. |
check_background_task | Checks on it. |
list_background_tasks | Lists what is running. |
wait_for_background_task | Blocks until it finishes. |
kill_background_task | Stops it. |
This is what makes a test suite, a build, or a long install something Perch can supervise rather than sit inside of.
The sandbox
For work that needs real computation rather than reasoning about numbers, Perch writes code and runs it in a sealed sandbox with run_sandbox_code. This is how a total gets computed instead of guessed.
The sandbox is hardened deliberately:
- Network disabled. The sandbox has no outbound access.
- macOS seatbelt. Execution runs under a
sandbox-execprofile, isolated from the rest of your machine. - Recorded provenance. Sandbox executions are logged, so a computed figure can be traced back to the code that produced it.
Planning and task tracking
Perch has first-class planning rather than an instruction to "think step by step":
- Plan mode lets Perch inspect the workspace and draft a plan, with mutating tools blocked until you approve it. You get a plan card, and nothing is written while you read it.
- Todos let Perch keep a visible task list across a long run, so you can watch progress instead of guessing at it.
- Questions. When Perch is genuinely blocked on a decision that is yours, it asks rather than picking for you.
Chat modes
The composer has three modes, and they change what a turn is allowed to do:
| Mode | Behavior |
|---|---|
| Ask | Conversation. Ask about the folder, the uploads, or what to do next. |
| Plan | Perch inspects, drafts a plan, and waits for approval before acting. |
| Agents | Perch plans and executes the task. |
Permission modes
Separately from the mode, a permission setting governs how much runs without approval. This is risk-tiered rather than a single on and off switch:
| Mode | What runs without asking |
|---|---|
| Default | Nothing risky. Writes, commands, sends, deletes, and other irreversible actions all require approval. |
| Auto Review | Low and medium risk reversible work runs automatically. High risk reversible work and every irreversible action still require approval. |
| Take the Wheel | Full autonomy. Perch can write, delete, send, and take irreversible real-world actions without asking. |
| Plan | Read-only. Mutating tools stay blocked until a plan is approved. |
The distinction Auto Review draws is between reversible and irreversible, not between easy and hard. Editing a file you can undo is a different category from sending an email, and the permission model treats them that way.
Effort
The effort control sets how hard the model works on a turn. It is one bar of five segments: four effort levels, then a separate notch for Flock.
| Setting | What it means |
|---|---|
| Off | No thinking. Fastest, and lightest on your usage. |
| Low | Shallow reasoning. Short scoped tasks where speed matters. |
| Medium | Balanced. Fewer, more consolidated tool calls. |
| High | Default. Complex reasoning and agentic work. |
| Flock | Not an effort level. Plans a team of workers and runs them in parallel. Best for big, splittable jobs. |
The interesting part is underneath. Providers express reasoning in completely different ways: some models ignore reasoning parameters entirely, some take a single on and off switch, and others expose their own named ladder. Each model in the registry declares which of those it is, and the effort you pick is coerced against the model that actually resolved for the turn.
That means one control behaves consistently no matter which model Roost routed you to or which one you pinned by hand. The bar never promises a model something it cannot do.
Sub-agents
Perch can spawn helpers during a turn, and you choose what model they run on. The default is Inherit, which follows the model doing the main work. Naming a different one is how you get one model checking another's work rather than grading its own.
This setting also covers background delegates. A named model costs more than leaving routing automatic.
See Sub-agents for the full picture, and Operator and agents for how the four multi-agent modes differ.
Skills
Perch carries a pack of operator skills that load only when they are relevant: workspace navigation, GitHub and git, documents, spreadsheets, presentations, PDFs, diagrams, research, data quality, and browser operation. Each one is a set of instructions plus preferred tools for a kind of work, and metadata stays cheap to scan while the full instructions load only on a match.
Skills are built in and are not user-authorable today.
Project rules
Perch reads standing instructions from your folder on every turn, from .perch/PERCH.md and .perch/rules/, plus a global manual at ~/Documents/Perch/PERCH.md. Rules you put there override Perch's defaults.
See Memory for how project files, durable memory, and learning from corrections fit together.
