Agent Runs

Normally you send Pia a message and it replies. In Agent mode you give it a goal instead: Pia writes a plan, works through it step by step, uses tools along the way, and checks its own result at the end. A panel above the chat shows exactly where it is and lets you steer.

Switch to Agent Mode

At the bottom of the message box there’s a two-position lever: Chat and Agent. Click Agent, type your goal, and press Enter.

A few things to know before you flip it:

The lever is greyed out if your current persona has tools switched off — Agent mode needs a persona with tools. Pick a persona with tool access and it becomes available.
If your provider isn’t a strong planner, Pia warns you before starting: This provider may not plan reliably. You can Continue anyway, Choose provider…, or Stay in Chat.
A goal needs a bit of substance. Send something very short and Pia tells you This looks too short to run as a goal. Add a few more words so it can be planned.
The lever belongs to this conversation. Flipping it here doesn’t change what your next new chat starts on — that’s Start new chats in Agent mode, under Settings → Assistant → Agent runs.
A question is answered, not planned. Ask one with the lever on Agent and Pia replies in one turn and marks it Answered directly, rather than drawing up a plan for it.

Taking the conversation with the run

A run started inside a chat can carry that conversation with it, so a follow-up like “the file isn’t in the working folder” is planned against what was already said.

A bar above the message box asks once per chat, and holds sending until you pick:

Choice	What the run is given
Send a summary	A short digest of the conversation so far.
Send the conversation	The conversation itself, word for word.
Send nothing	Just your goal, as if the chat weren’t there.

The bar doesn’t cut in while a run is already going, and it doesn’t appear for a run that isn’t coming.

The Run Panel

Once a run starts, a panel appears at the top of the chat. Its header shows the run’s state:

State	What it means
Planning	Pia is working out the steps.
Running	It’s working through the plan.
Delegating	It handed part of the work to sub-agents and is waiting on them.
Waiting for you	It needs an answer, an approval, or a decision from you.
Paused	You paused it.
Completed	It finished.
Failed	It couldn’t finish.

Under the state you get a live line about what’s happening right now — Building a plan…, Working…, Checking the work…, Waiting for your approval to use write_file — plus how far along it is (step 3 of 7), the elapsed time, and the tokens used so far.

The plan itself is listed as steps. The one it’s on is marked now, finished steps sit above, and long plans fold the middle away (4 earlier steps — all done, 3 later steps — pending) so the current step stays visible.

The clock runs while the run thinks. Drawing up a plan can take half a minute, and the panel keeps counting through it rather than looking hung. It deliberately stops while a run is waiting on you.

Seeing what a step is doing right now

A step writes its answer only when it finishes, so the conversation used to sit still for minutes. While a step works, the panel and the conversation below it now show how many tools it has used and which one was last — so you can tell the difference between working and stuck.

When Pia can’t build a plan

Two things can happen instead of a plan, and both say so rather than leaving you an empty box:

A step Pia can’t read is dropped on its own, and the rest of the plan holds. One step naming two files used to be enough to discard the whole plan.
If no plan can be built at all, the run reads “could not build a plan — working through the goal in one turn”, which is what it is doing.

Approving the Plan

When Pia proposes a plan, it posts it in the chat — Proposed plan — review the steps below, then Approve or Reject in the run panel — and waits.

Read the steps, then click Approve or Reject in the panel. Rejecting drops the run and leaves a note in the chat.

Steering a Run

You’re not locked out once it’s going.

Pause stops the run at the next safe point. Occasionally it has already moved on — Pia says so and you can try again.

Continue restarts a run that’s paused or has hit one of its limits (Stopped at budget — continue?). Before you continue, you can add a Note for the rest of this run — for example keep the summary under 200 words. The note travels with every remaining step, its checks, and any re-planning. It isn’t saved and doesn’t survive a restart.

Change the plan. Pause first (Pause the run to change its plan), then each step gets a menu:

Edit step — change its short title and what the assistant is actually asked to do
Insert step below
Move step up / Move step down
Skip step

Then continue, and the run picks up the plan you left it.

Tool Activity

Expand Tool activity to see every tool the run touched, grouped by step, with what happened to each one:

Decision	Meaning
Approved	You allowed it on the card.
Auto-approved	It ran without asking — you’d granted it before, or agent autonomy covers it. See Tool Permissions.
Denied	You said no.
Blocked	Pia refused it — it wasn’t allowed in this run.
Awaiting approval	It’s waiting on you right now.

Tool activity counts what happened, not how often it was asked. Approving one call is recorded once, and as yours rather than automatic.

Very long runs record only the first stretch of decisions and say so (Trace shortened).

If the run split work across sub-agents, they get their own section with a 2 of 3 finished counter and a timeline each.

Working notes are not put to you for approval

Pia drafts its own working notes under a .scratch/ folder, which is never published. Those writes run without a confirmation card, and they don’t appear as a second file link beside the deliverable they were notes for.

A run clears its working notes away when it finishes. Normally they go with the run’s private copy of your folder; a run that could not make one writes them into the folder itself, and those are cleared too. Only files the run actually wrote are removed.

Where the Files Go

An agent run doesn’t edit your folder directly while it works — it works in its own copy, so a half-finished run can never leave your files in a mess.

If your assistant folder is a git repository (and git tools are on), the run gets its own branch. When it settles, the panel tells you Output is on branch pia/run-….
Otherwise Pia takes a bounded copy and moves the work back when the run settles.

Which folder a run writes into is the chat’s working folder, and a routine writes into its own. That holds even when the folder is too large to set aside for the run — those runs put their files at the top of your assistant files folder instead.

If any files are still sitting in the run’s workspace, the panel says This run’s files are still in its workspace and offers a Publish files button. Click it and Pia moves them across, then reports how many landed.

Run It in the Background

In Agent mode a Run in background button sits next to Send. It detaches the run so you can carry on elsewhere — it keeps going, keeps writing into the chat, and lets you know when it’s done via Flow.

While a detached run is writing to a chat, the message box shows A run is writing to this chat. Sending resumes when it finishes.

Closing the window while a run is going

Closing a Pia window with the X does not stop a run. The X hides the window and leaves Pia running in the system tray, so the run carries on exactly as it was, and lands in Flow when it finishes or when it needs something from you. Bring the window back with the tray icon or the Ctrl+Alt+P hotkey and the run panel is where you left it.

What does stop a run is Exit from the tray icon’s right-click menu — that quits Pia properly, and an interactive run ends with it. If you’re about to quit and want the work to survive, detach it with Run in background first, or put it on a routine.

A run that was interrupted doesn’t leave your files half-edited: it works in its own copy, so anything it hadn’t published is simply not applied. See Where the Files Go.

Background runs get more generous limits than interactive ones, because nobody’s watching. Want one on a timer instead? See Routines.

Limits and Settings

Open Settings → Assistant → Agent runs. These are the walls a run stops at, so it never runs away. A run that reaches one pauses and waits for you.

Setting	Default	What it does
Maximum steps	24	How many steps a run may take.
Maximum tool rounds per step	24	How often the model may call tools and re-consult itself inside one step.
Time limit	20 min	How long a run may take.
Re-plans on failure	2	How many times a run may revise its plan after a step fails.

Planning

Think before planning (off) — adds a short tool-free thinking turn before the plan is written, so the model can reason at the effort you configured. Helps on providers that switch reasoning off while tools are attached, and doubles the cost of the planning turn.

Autonomy

Auto-approve Pia’s own write tools during agent runs and in voice mode (off) — lets Pia create and change files, notes, tasks, reminders and routines without asking each time. Deleting anything, git commands, and external (MCP) tools are never covered. See Tool Permissions.

Step specialists

Pick up to six personas the planner may assign to individual steps. An assigned step then runs on that persona’s own prompt and provider — a coder persona for the code step, a writer persona for the summary. Leave it empty and every step runs on your default assistant.

Background & scheduled runs

Separate, more generous limits for detached and scheduled runs: 24 steps, 45 min, 2 re-plans, and 2 background runs at the same time. Extra runs still start — they just wait for a free slot.

Next Steps

Tool Permissions — decide what runs without asking
Routines — put an agent run on a timer
Coding Tools & @Files — the folder a run works in