Background agents
Durable side agents, the Agents panel, questions, permissions, and limits.
A thread's main agent can start background agents for side tasks, such as running the tests while it keeps editing or reviewing a module in parallel. Background agents run in a durable host. They keep running when you close the window or when pi-kit or its backend restarts.
Enable or disable per project#
Background agents are on by default for trusted projects. To turn them off for a project, open Settings → Projects, select the project, and turn off Background agents. Untrusted folders never run background agents.
How the main agent uses them#
The main agent has tools to start an agent with a brief (
agent_spawn), message it (agent_send), list agents (agent_list), wait for a result (agent_wait), and stop it (agent_stop). Each start appears as a card in the transcript.An agent sends its result back with a report. Reports appear in the thread as they arrive. Messages from an agent are labeled From agent ‹name› and fold into one row in the transcript.
For example:
Start a background agent that runs the full test suite and reports failing tests. Keep working on the parser change meanwhile.
Agents in the same thread can find and message each other.
Video walkthrough · English captions
Run background agents with Qwen 3.6
Delegate independent test planning and command-line review to two read-only background agents using Qwen 3.6 through LiteLLM. Inspect progress and bring their reports back into the main plan.
The Agents panel#
Open Agents from the side-panel switcher next to Artifacts. The panel lists Active and History agents for the current thread.
Each card shows the state, running time, turns, tokens, spend, and permission mode. Use Open to read the agent's brief, allowed tools, and transcript; Stop to end a run; and Delete to remove it. The open view has a composer for steering a running agent or sending a follow-up.
After a restart, an agent whose command may still have been running, or one that restarted three times in ten minutes, is held. Choose Resume or Discard and resume.
Questions from agents#
An agent can ask the main agent or you a question. The main agent answers directly or forwards the question to you. Questions for you appear in the thread as Question from agent ‹name›, count toward Needs you in the sidebar, and are listed in the Agents panel with Answer and Dismiss.
For a question addressed to the main agent, Override sends your own answer instead. Pending questions survive a restart. A question with a timeout receives its default answer when the timeout expires.
Permissions#
| Mode | Behavior |
|---|---|
| Read-only (default) | Reads files and runs read-only commands. Common test, lint, and type-check runners are allowed. |
| Edit | Can change files in the thread's checkout and takes coordination leases to avoid conflicting edits. |
| Isolated | Works in its own Git worktree, removed when the agent is deleted. |
When a read-only agent attempts a blocked action, you can choose Allow once, Allow all, or Deny. Allow all switches that agent to edit mode for the rest of its run. Agent edits appear in Changes.
Usage and costs#
Background agents have no turn budget, spending cap, or message limit: they run until their task is done or you stop them. Each card shows the agent's turns, tokens, and spend as it works, so you can stop one that runs longer than expected. pi-kit generates for at most four agents at the same time; further agents wait their turn.
Background agents use the configured models and may incur provider costs. Spend figures are estimates from reported token usage; local models report no spend.
Current limits#
- Process cleanup after a crash is best effort.
- The packaged-app smoke test, which starts and finishes a background agent, passes on macOS and on Linux x64 and ARM64 under Xvfb. It has not yet been run on Windows.
- Searching or reading other sessions from an agent, and starting an agent with the full thread context, are not available yet.