PerchAI
Using Perch

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.

A normal turn does what you asked and stops. If the job takes twelve steps, you keep saying "continue". A goal removes that: you state the objective once, and Perch re-invokes itself turn after turn until an independent check agrees the work is done.

The short version

/goal <objective> in Perch Terminal or the CLI. It runs across many turns, survives quitting, and stops on its own at 40 turns or 4 hours. /goal on its own shows where it stands.

Setting one

/goal make the test suite pass
/goal reconcile every invoice in this folder against the ledger and write up the exceptions

Reach for a goal when the work has many steps and a finish line you could describe out loud. Do not reach for it for a single question: a goal that could have been one turn only adds an audit step.

Starting /goal again with exactly the same objective text continues the goal you have, keeping its turn count. Different text starts a new one.

Watching and steering it

CommandWhat it does
/goalShow the goal: its status, turns used, why it last stopped, and what the completion check last said.
/goal pausePause it without losing it.
/goal resumePick it back up where it stopped.
/goal clearDrop it. stop, off, cancel and reset all work too.

/goal status is the same as bare /goal, and /goal continue is the same as /goal resume.

While a goal runs you see each turn as it happens, with its tool calls. Esc in the desktop app, or Esc on an empty input or Ctrl-C in the CLI, stops the current run.

The completion check

Perch does not take its own word that a goal is done. When a run declares the objective met, a separate check reviews that claim, and it can come back three ways:

  • Met. The run ends as complete.
  • Not met. Perch keeps working with what the check found. If the run ends there, it tells you what was missing and you can resume.
  • Not possible. The check found the objective cannot be met at all. The run stops and says why, so you can change the goal rather than burn turns on it.

The last thing the check said is part of /goal status, so you can always see what it is holding out for.

Where a run stops

A goal never runs forever. Every end state except complete can be picked back up with /goal resume.

StopWhat it means
CompleteThe completion check passed.
BudgetIt hit 40 turns or 4 hours of wall clock. What you have is partial progress.
IncompleteA turn made no tool calls and did not pass the check, so it stopped rather than spin.
BlockedAn action needs your approval, or the run hit something it cannot do unattended.
PausedYou paused it, or a usage limit paused it.
FailedA turn errored.
CancelledYou stopped it.
InterruptedThe run's process died, for example because the app quit mid-turn.

A step that stops responding also ends the run, rather than hanging on it.

Permission modes matter here

A goal is meant to run without you, and Default permission mode stops at the first write or command to ask. So a goal started in Default runs in Auto Review for that run, and Perch says so when it starts: reversible work runs on its own, and higher-risk actions still get a safety check. Take the Wheel and Plan stay as you set them.

Auto Review still comes to you for the highest-risk actions. When that happens the goal reports Blocked and waits. See permission modes.

It survives quitting

A goal is saved with its thread, so it outlives the session. Quit the CLI, close the desktop app, or reload the page, then come back to the same folder or thread and run /goal resume. The objective and the turn count are still there.

Two things follow from goals being per thread. A goal set in one folder's thread is not visible from another, because the CLI scopes the default thread to your working directory. And a usage limit that paused a goal may let it resume on its own until you start a turn of your own; a goal you paused never resumes by itself.