PerchAI
Using Perch

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:

ToolWhat it does
run_in_backgroundStarts the command as a detached job and returns at once with a task id.
list_background_tasksLists the tasks and their state.
check_background_taskReads the newest output without blocking.
wait_for_background_taskBlocks until it finishes.
kill_background_taskStops 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 dates

Use 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.