Process Guard

  • Desktop app
  • All plans
View as MarkdownFeature page

What it does

An AI agent spawns a real system process for every tool it calls (a search, a build, a script). Most end in seconds; some never do, keep holding gigabytes of memory while using no processor, sometimes outlive the agent that started them, and pile up until the machine is unusable. Process Guard sweeps the child processes of agent terminals, measures their real memory footprint (compressed memory included on macOS, swapped pages on Linux, private commit on Windows), flags the ones that are stuck, one by one or as a crowd, names the agent responsible and lets you end them. By default it never terminates anything on its own.

Where to find it

  • The Processes chip in the status bar at the bottom of the window. It shows the count of stuck processes; click it to open the Protecting your machine panel.
  • A toast the first time something is flagged ("Stuck process"), with an End the process action.
  • Settings > Terminal > Stuck process guard.

How to use it

  1. Leave it on. When the chip lights up, click it: each row shows the command that was run, Started by which agent, the memory it holds, its age in minutes and its CPU share, plus Orphan: its agent is gone when the parent has exited.
  2. Click End on a row. The memory comes back immediately. The agent keeps running: its tool call receives an error instead of hanging forever, nothing is restarted, no context is lost.
  3. When one agent has several heavy commands in flight, the panel groups them ("This agent has N commands running at once") with End all N and Interrupt the agent. Interrupt sends Ctrl+C to that agent's terminal: its turn ends, it waits for you, the session stays open. It exists because an agent that reads a swap-induced slowdown as a freeze tends to start yet another copy of the same command.
  4. Open this agent jumps to the terminal that started the process.

Settings

  • processGuardEnabled (global, Settings > Terminal > Stuck process guard): watch the child processes of agents. Default on.
  • processGuardMemoryMb (global, "Report above"): footprint a stuck process must hold to be reported. Default 2048 MB (slider 512 to 16384). A process that is still using the CPU must hold twice this amount before being reported, and is never ended automatically.
  • processGuardIdleMinutes (global, "After at least"): age before a process is measured. Default 5 min (slider 1 to 60). A process already holding 5 % of the physical RAM is measured whatever its age.
  • processGuardAutoKill (global, "End stuck processes automatically"): act without asking, with a notification after the fact. Default off. Never touches a process that is still busy, nor a member of a pile-up.

Agent tools (MCP)

None. The guard is a safety net for the user; agents are not told about it and cannot drive it.

Providers

All providers, no difference. The guard watches the children of whatever agent terminal you started; the CLI itself, the shell and the app's terminal helper are protected based on the binary used at launch, not on a list of names.

Mobile

Not on the mobile companion.

Limits

  • Dev terminals are never watched: an idle dev server matches every runaway criterion (large, old, no CPU). Their memory is counted to judge how full the machine is ("held by terminals you started yourself"), but they are never listed nor ended.
  • Pile-up rule: when the measured footprints of one scan exceed half the physical RAM, every agent process above 256 MB is reported ("Reasonable on its own. Flagged for what the others are holding at the same moment"), provided at least two agent processes hold a quarter of the RAM between them. Pile-up members are never ended automatically.
  • Cost: one process snapshot per minute (about 40 ms on a machine with 800 processes); the expensive footprint probe only runs on processes that already look suspicious, and nothing runs while no agent is open.
  • Works on macOS, Windows and Linux, each with its own memory measurement and its own orphan detection.
  • It treats the symptom, not the cause: a tool that goes wrong today will be another one tomorrow.

Common questions

  • Does AgentsRoom slow down my computer? On the measured session the app used 2.8 GB across 91 processes and eight agent CLIs 1.6 GB; the 41.8 GB were held by seven stuck search processes. The guard exists to name them.
  • Will it kill my build? It never ends one without asking. A running build has to hold twice your threshold (4 GB by default) just to be reported.
  • Twelve processes, none over my threshold. Will it say anything? Yes: judged together they can fill the machine (measured: twelve type checks from six agents, 15.4 GB on a 16 GB machine). That is the pile-up verdict.
  • Why not read Activity Monitor? On macOS the resident column understates a compressed process by an order of magnitude (20 MB resident for 8 GB held). The guard measures the real footprint.
  • What happens to the agent when I end its process? It keeps running; its tool call gets an error instead of waiting forever.

Related