Running agents

The Running view lists every agent conversation running on this computer, whichever harness and terminal it runs in, and the ones that finished in the last hour. Each row says what the agent is doing now, and the ones that need you come first. Agent sessions also keep running after their work ends, holding memory and MCP servers until their terminal closes, so the view stops the ones left idle too.

App

Running

CLI

hansard ps

Work by project

Running opens with one card per project in its sidebar. A card shows the agent that most needs you, its state and time, and the project’s branch, folder, and the ports its agents listen on. Right-click a card for Pin to top, New conversation here, and Open project page.

Select a card to open the project’s conversations as tabs across the top. Each tab shows the agent’s mark, its title, and a short time, tinted by its state.

• Select × on a tab to close it. The agent keeps running, and the tab comes back when the agent needs you or starts working again.
• Tabs that do not fit, and the tabs you closed under Closed tabs, are in the menu at the end of the row.
• Command+Shift+] and Command+Shift+[ move to the next and previous tab.

Beside the conversation, a right pane holds up to three panes. Its menu adds a Changes, Files, or Terminal tab, or a localhost:<port> tab for a port an agent listens on, and offers Split right, Split down, and Close the right pane. Each project keeps its own tabs and panes.

To list every agent in groups instead, set View options → Sidebar to Agents.

See running conversations in the app

1. Select Running in the app dock, below Sessions.

2. With View options → Sidebar set to Agents, review the groups:

   • Needs you lists agents waiting for an approval, a question, or a reply, and agents that reported they are blocked or need review. To answer them all in one queue, open Review.
   • Working lists agents at work.
   • Done or idle lists agents waiting at their prompt and conversations whose agent exited in the last hour, marked Finished, Failed, or Interrupted.

   Select a group’s name to fold it. Agents idle for over an hour sit at the end of the list in Idle for over an hour, which starts folded.

3. Select a row to open its conversation beside the list, where you can read it and reply. An agent whose conversation Hansard has not archived yet opens the Hansard terminal it runs in, or a page with its process facts.

Right-click a row, or press the menu key, for its menu. Show in followed by the agent’s terminal app, such as Show in iTerm2, brings that app forward on macOS. cmux also selects the agent’s own tab once cmux accepts Hansard. Stop agent stops the agent.

Each row shows the agent’s mark, the conversation’s title, its state dot, and one line with the agent’s latest action and when it happened:

• a tool call, such as Editing src/cart.ts or Running npm test
• Compacting
• an approval, such as Waiting for approval: Bash
• the first words of the agent’s latest message

A conversation that runs in two places, such as in Hansard and in another terminal app, stays one row, marked with the number of copies. Point at the mark to see where each copy runs.

Approvals and errors show in the warning color. Without a recent action, the line shows the project. On an idle Claude Code or Codex agent, the time’s tooltip says whether its prompt cache is still warm.

State comes from the harness’s own records where it keeps them, as Claude Code and Codex do, from Hansard’s own runs, and from CPU use otherwise. With Claude Code activity on, Claude Code rows also show API errors, such as Rate limited, and compaction sizes.

Sort, filter, and search

Select View options at the top of the list:

Option	What it does
Display	Conversation opens the selected conversation beside the list. Terminals shows up to four agents side by side. See Watch agents side by side.
Sidebar	Projects, the default, lists one card per project with its conversations as tabs. Agents lists every agent in groups.
Sort	Needs you first groups rows by state. Recently updated, Recently started, and Manual order show one list.
Agents	Shows only the harnesses you choose.
Finished in the last hour	Turn it off to list only running agents.

In Manual order, drag a row to a new place, or press Option+Up and Option+Down to move the focused row. A conversation the order has not seen joins at the top.

Select the search button to filter the list. Search matches each word against the title, project, folder, agent, state, and latest action. Press Escape to clear it.

To jump to the next agent that needs you from any view, press Command+Shift+U.

Review memory by folder

Select Activity overview at the top of the sidebar to group process memory by Git checkout. With Sidebar set to Agents, choose By folder under View options → Sort instead. Main checkouts and worktrees stay separate. Small groups fold together, and Not a checkout holds the remaining processes.

With no checkout selected, the overview shows total memory, macOS memory pressure, and the processes in each group:

Group	Processes
Agents	Coding agents and their children
Shared	Hansard services, databases, and containers
Stacks	Development servers listening on a port
Build	Compilers and watchers
Left running	Servers left running without a terminal
Other	Remaining processes

On macOS, memory uses each process’s physical footprint, as Activity Monitor does. A development server, build, or process left running offers Stop, with a confirmation. Pause stops agents idle for over an hour and frees their memory, and their conversations stay saved. Resume returns an agent to the terminal where it ran. Evict removes a paused row from Running but keeps its conversation in Sessions.

In a terminal, hansard ps lists the same agents with their subagents and the paused agents, hansard ps --by-folder lists them by folder, hansard ps pause <pid> and hansard ps resume <id> pause and resume an agent with the same rules as Running, hansard ps evict <id> removes a paused row as Evict does, and hansard ps stop stops idle ones.

See agents as a graph or in lanes

The overview’s header switches between Activity, Graph, and Lanes. Graph draws every running agent with its subagents, the tools and MCP servers it calls, and you. Each call pulses along its link, and an agent that waits for you turns amber. Lanes shows one lane per running agent over the last 30 minutes, with each turn as a block named by its task and its subagents in rows under it.

Automatic pause

Hansard pauses an agent after 65 minutes idle at its prompt, once its prompt cache has expired. It checks the last model request and terminal input before pausing. Agents with work, approvals, queued input, commands, subagents, scheduled jobs, or a delegation remain running.

Under critical macOS memory pressure, Hansard can also pause agents idle for 15 minutes, largest first, until pressure eases. Warning-level pressure does not trigger this earlier pause. Running shows when each agent paused and why.

Change these in Settings → Handoff & helpers → Pause and Resume, or with the matching configuration keys:

Setting	Key	Default	Effect
Pause idle agents	agents.autoPause	true	Pause idle agents. Turning it off disables all automatic pauses.
Pause under memory pressure	agents.pauseUnderMemoryPressure	true	Allow earlier pauses under critical macOS memory pressure.
Resume for requests	agents.wakeForRequests	false	Resume a paused agent for an explicit peer work request. Otherwise the request waits, and the sender’s receipt and Running say the agent is paused.

For example, to keep idle agents running:

hansard config set agents.autoPause false

Resume command at the prompt

When Hansard pauses an agent that a shell started, by Pause or automatically, the agent’s resume command waits at that shell’s prompt. There is no separate switch.

Terminal	How the command arrives
cmux	Pasted into the tab through cmux’s socket, without Return. When cmux’s Socket Control Mode is cmuxOnly, cmux refuses Hansard and the shell hook is used.
tmux	Typed into the pane, without Return.
Terminal, iTerm2, Ghostty, Warp, and others	The shell hook.

Hansard adds the shell hook to ~/.zshrc (or the file under ZDOTDIR) and ~/.bashrc once an agent runs in a terminal that needs it. Shells that start after that carry it. The first time it acts, it names the file it changed and how to remove it. In zsh, the command is ready for Return. In bash, Up then Return selects and runs it.

To remove the hook and keep the command off every prompt:

hansard config set agents.resumeCommandHook false

A hook block removed from a startup file by hand stays removed.

Start a conversation

1. Select New conversation at the top of the Running list. The New conversation button in Sessions and the command palette open the same place.
2. Choose the harness, the folder, and the device, then type the first message and send it.

The new agent joins the list at once, marked Starting, and moves to its place when its process starts. Its conversation then opens in place of the composer.

Bring a conversation back into Running

1. Open an older conversation in Sessions.
2. Select Actions → Open in → Open in Running.

Running opens the conversation with its row selected in the list, marked Resuming, and the agent’s own CLI resumes in the conversation’s terminal. In the command palette, select a conversation and press Option+Return to do the same.

Watch agents side by side

Set View options → Display to Terminals to watch up to four agents at once, as in cmux. Rows then also show each agent’s git branch, folder, and the ports it listens on, and an agent that needs you takes a ring in the warning color.

1. Select a row to show its agent in the focused pane.
2. To add a pane beside it, Command-click another row (Control-click on Windows and Linux), or choose Open in a split in the row’s menu. A fifth agent replaces the focused pane.
3. Press Command+Shift+] and Command+Shift+[ to move between panes. Close pane, in a pane’s menu, removes it.

Each pane shows its agent the best way Hansard can reach it, and says which under its bar:

• An agent in a Hansard terminal shows that terminal, live.
• An agent in tmux shows its own tmux pane, live, and you can type into it. Hansard joins the agent’s tmux session without moving your other tmux windows. This works for agents on the default tmux server.
• Any other agent shows the latest messages of its conversation and its latest action, with Show in followed by its terminal app.

Terminal support lists what Hansard can do in each terminal.

Stop agents in the app

• To stop one agent, select Stop agent in its row’s menu, or in its conversation’s Actions menu, and confirm.
• To stop every agent idle for over an hour, point at Idle for over an hour at the end of the list, then select Stop all N and confirm. The confirmation says how much memory they use.

A stop asks the agent to exit, as closing its terminal does. If the agent is still running a few seconds later, Hansard offers Force stop, which ends the agent and every process it started at once.

The conversation stays saved. Resume it later in the harness, or select Resume in Hansard or Resume in terminal under Actions → Continue conversation. Hansard never stops the agent that runs Hansard itself.

For an agent running in one of Hansard’s terminals, Actions → Open in → Show terminal opens that terminal beside the transcript.

Watch processes in the process monitor

Process monitor, the first row of the list, shows how many agent processes run and how much memory they use. Select it to see:

• Agents, with how many work and wait
• Memory, counting every process the agents started, including MCP servers, shells, and tool commands
• CPU, as a share of one core
• Idle over an hour, with the memory those agents hold

Below the figures, the agent processes are grouped by state. Select one to open its conversation.

Select Show in terminal to switch the monitor to a terminal that runs hansard ps --watch. Show as list switches back. Use the arrow keys to choose an agent:

Key	Action
s	Stop the chosen agent.
f	Force stop the chosen agent.
x	Stop every agent idle for over an hour.
i	Show only agents idle for over an hour.
q	Quit the monitor and keep using the shell.

The monitor refreshes every two seconds. Run hansard ps --watch in any terminal to open it outside the app.

List and stop agents from the CLI

hansard ps                      # every running agent with its CPU and memory
hansard ps --harness codex      # one harness
hansard ps --idle               # only agents idle for over an hour
hansard ps stop --idle          # list the idle agents, then ask before stopping them
hansard ps stop 4242            # ask one agent to exit
hansard ps stop 4242 --force    # end one agent and everything it started at once

Option	What it does
--harness <name>	Show one harness, by name or command: claude, codex, cursor-agent, gemini, opencode.
--idle	Show or stop only agents idle for over an hour.
--watch	Open the full-screen monitor.
--force	End the agent and every process it started at once instead of asking it to exit.
--yes	Stop idle agents without asking first. A script without a terminal needs it.
--json	Print a machine-readable result.

The table fits narrow terminals by leaving out secondary columns. Before it signals a process, Hansard checks again that the process is still the same agent.

Terminal support lists the terminals Hansard recognizes and what it can do with an agent in each.

Note

The list shows agents on the computer that runs Hansard. A remote or read-only viewer does not show the Running view’s list.