Background tasks
Long commands and delegated agents run in the background while you keep the chat, and Perch can pick the work back up on its own when one of them finishes.
Some work takes minutes: a test suite, a build, a long install, a job you would rather not watch. Perch can start it, let go of it, and come back to it when it is done, instead of sitting inside the command while the conversation waits.
Two different things run in the background, and they are worth telling apart.
Background commands
A background command is a program Perch starts on your computer and does not wait for. The turn carries on, and the command keeps running after the turn ends.
Perch drives them with five tools:
| Tool | What it does |
|---|---|
run_in_background | Starts the command as a detached job and returns at once with a task id. |
list_background_tasks | Lists the tasks and their state. |
check_background_task | Reads the newest output without blocking. |
wait_for_background_task | Blocks until it finishes. |
kill_background_task | Stops it. |
What the harness guarantees:
- The record survives restarts. Tasks are kept on disk, so quitting the CLI or closing the app does not lose track of them. A task whose process is gone when Perch comes back is reported as unknown rather than silently running.
- Output is captured to a file. Perch keeps the combined output, capped, with the start and the end kept when a task writes more than the cap. Tool results show a short preview rather than the whole log.
- A limited number at a time. Only so many background tasks run on one machine together. Past that, a new one is refused until one finishes or is stopped.
- One hour. A watchdog stops a background task that has run for an hour.
Ask for it in words. "Run the test suite in the background and keep going" is enough.
Perch coming back to a finished task
The useful part is what happens when a background task ends. Perch can start a turn of its own to read the result and pick the work back up, so a build finishing is what moves the task forward rather than you noticing and saying "ok, now what".
That only happens inside guardrails:
- Only in Auto Review and Take the Wheel. In Default, Perch never starts its own turn, because the point of Default is that you are there to approve each step.
- Not for trivially fast commands. A command that finished in under a couple of seconds does not wake anything. Otherwise a quick command would turn into an expensive loop.
- A hard ceiling per chat. Self-started turns in one chat are capped, so a task that keeps restarting itself cannot spin forever.
The transcript labels these turns, so you can always see that Perch started one rather than you.
Background agents
A background agent is a whole task handed to a helper rather than a single command. /delegate <task>, or /bg, hands a scoped task to an agent that runs on its own; the result arrives in the same chat when it finishes.
/delegate summarize every PDF in ./contracts and list the renewal datesUse it when the task is self-contained and you would rather keep working than watch. If the task needs your input partway through, or you want to steer it, keep it in the main session.
In the CLI, /agents lists this chat's agents, /agents <id> prints one agent's steps and report, and /agents stop <id> stops it.
Agents are bounded the same way background commands are: a step cap of their own, 30 minutes of wall clock, and 10 minutes without output counted as stalled. Every result says why the agent stopped, including when it hit a limit. /delegate needs a session that stays open, so it is not available in a one-shot perch run.
For the helpers Perch spawns inside a turn, and for sub-sessions, see Sub-agents. For a whole team of workers on one task, see Flock.
Goals
A goal is an objective Perch pursues across turn after turn on its own, with an independent check on whether it is actually done, until it finishes or runs out of budget.
Deep research
A research run that plans a question into parts, searches your files and the web across several rounds, and comes back with a cited report and a ledger that separates what your files back from what only the web says.
