Following a live agent session

When an agent picks up a task, CodeHerder spawns a clean session for it and starts a terminal process on the assigned device. The Sessions view gives you a live window into every session running right now, so you can watch progress, step in when needed, and review what a finished session accomplished.

The Sessions sidebar view

Sessions appears in the sidebar of every workspace. A number badge next to the label counts the sessions running right now — it updates automatically as agents start and finish work.

Click Sessions to open the full list.

The session list

The list shows one row per session, and its heading changes to tell you what you’re looking at:

Heading	When	What it shows
Running now	Live only checked (the default)	Only sessions with an active terminal right now.
All open sessions	Live only unchecked, Include closed off	Every session that hasn’t finished yet, live or idle.
All sessions	Include closed on	Everything, including sessions that already finished or were abandoned.

When Live only is off, a subtitle next to the heading (for example “3 live”) tells you how many of the listed sessions currently have an active terminal, since the list itself is no longer filtered down to just those.

The list loads a batch of sessions at a time and pulls in more automatically as you scroll to the bottom. A Load more link also appears there, as a manual fallback if you’d rather click than scroll. There’s no fixed cap — keep scrolling (or clicking Load more) to reach every session that matches your filters.

Columns:

Column	What it shows
Type	For a task-driven session, the task’s own type badge (for example story or bug), or a plain task badge if the type isn’t known; for an interactive dev session, dev.
State	The session’s lifecycle state. A green dot marks sessions that are actively running right now.
Agent	The agent template that spawned this session.
Working on	The task this session is working, with its current stage badge.
Device	The device the session is running on.
Repo	The repository this session’s isolated worktree is checked out from.
Cost	The model spend so far for this session. A smaller second line, task $X, shows the lifetime spend across every session of that task — not just this one.

Filter controls:

• Live only — checked by default. Shows only sessions with a running terminal.
• Include closed — unchecked by default. Turn this on to include sessions that have already finished or been abandoned.

What the state badges mean

The State column uses one vocabulary for the list, and a session’s own page (see The live-terminal page below) uses a different one — keep them apart:

• In the Sessions list, a task-driven session moves through Provision → Ready → Active → Completing → Done, or ends Abandoned. A dev-session row can also read Stopped or Archived — see Interactive dev sessions for what those mean.
• On a session’s own page, the state is one of Starting, Running, Exited, Killed, or Lost — the state of the terminal process itself, not the task’s workflow position.

Whichever vocabulary a badge uses, the green dot is the one signal that means the same thing everywhere: an agent process is running right now.

Queued and leftover sessions

Two badges appear above the list whenever there’s something worth your attention, even with Live only checked — they cover sessions that don’t have a running terminal, so they’d otherwise be invisible in the default view.

“N queued for a slot” means sessions have been set up and are waiting for a device slot to open — every device only runs so many sessions at once (see Concurrency and capacity). A queued session starts automatically the moment a running session on that device finishes and frees its slot; you don’t need to do anything. If this count is high or keeps growing, it’s usually the answer to “why hasn’t my new task started?” — see Why isn’t my task moving? for the full diagnosis.

“N on finished tasks” is a warning: it means N sessions are still open even though the task they belong to already finished, was cancelled, or was abandoned. A session like this isn’t doing anything useful — it’s just holding a sandbox slot that another task could be using. The same warning appears on the affected row itself (for example, “task done”) so you can spot it without checking the badge count first.

Retiring a leftover session

Open the leftover session’s task and find the Sessions panel on the task’s detail page — this is the same panel where you start a session as well as retire one:

• Launch session appears when the task has no live session, and sets up a fresh session for its current stage.
• Activate appears on a session that’s already set up but hasn’t started running yet, and brings its terminal online.
• Finish session wraps up a session that’s still actively working, moving it toward a normal close instead of abandoning it. The task’s assignee (or an admin) can use this one.
• Mark done appears once a session has moved into that closing state — typically right after Finish session — and closes it out for good: it stops the agent process if one is still attached and frees the slot, without touching the task’s own workflow stage. It sits at the same permission tier as Abandon, and the two appear side by side at this point.
• Abandon tears down the session’s sandbox immediately, without merging anything, and frees its slot. This is the right control for a leftover session — it’s terminal and can’t be undone, so only a workspace admin or owner can use it.

CodeHerder only shows you the controls you’re allowed to use, so if you don’t see Abandon on a session, you’ll need an admin or owner to retire it.

If a device looks fully busy but nothing seems to actually be running on it, that’s usually a different problem — leftover worktree slots on the device itself, not a leftover session. See Reclaiming stuck worktree slots in Managing your devices for that case.

Reaching a session from a task

Every task’s detail page has a Workflow view that shows which session ran each stage. If that session is still live, the row shows a ▶ Drop in button — clicking it opens the session’s live terminal. If the session has finished, the row shows a View → link that takes you to the same page with its recorded summary instead.

The live-terminal page

Opening a live session via ▶ Drop in (from either the session list or the task’s Workflow view) connects your browser to the agent’s running terminal.

Who can drop in: opening the terminal, using the Send box, viewing scrollback, and pressing Stop all require a human who is either a workspace owner or admin, or the session’s agent’s operator (the human who created that agent). Agents can’t attach to a session at all. Without that access, the terminal simply never connects — if a Drop in page seems stuck retrying and never reaches connected, this is usually why.

The page header shows a connection status pill:

Status	Meaning
connecting…	Opening the connection for the first time.
connected	The terminal is live and receiving output.
reconnecting (attempt N)	The connection dropped briefly; the page is retrying automatically, counting each attempt.
run exited	The session’s process finished; the terminal is no longer attachable.
run lost	The device running the session stopped reporting in — usually because it restarted. The terminal can no longer be re-attached.
rejected: …	The connection couldn’t be established — the pill names the cause, for example rejected: auth expired. Sign in again and reopen the session.

While a session is live, a Stop button appears in the header. Clicking it sends a stop signal to the agent’s terminal process. Use this when you need to halt a session that is going off-track. The button disappears once the session has finished.

Tip: If clicking or scrolling in the terminal seems to do nothing, a full-screen program running inside it has likely captured the mouse. Hold Shift while clicking or scrolling to use the page’s own scrollback and selection instead.

Sending input to a live session

There are two ways to send input to a running session, and they behave differently for the team’s audit trail.

Typing directly into the terminal sends keystrokes straight to the agent’s process. This is fast, but the keystrokes are not recorded in the team activity feed — a banner directly above the terminal reminds you of this whenever a session is live. On a phone, an on-screen key row below the terminal (Esc, Tab, ⇧Tab, and the four arrow keys) — pinned in place as you scroll — lets you answer an agent’s interactive prompts without a physical keyboard; these keys count as direct typing and are not recorded either — the banner covers both.

Using the Send box (below the terminal) sends text through CodeHerder’s API. This input is recorded in the activity feed, so the team can see what you sent and when. The Send box carries plain text — newlines and tabs survive — but it can’t send Escape or other control keys; use the terminal itself (typed or via the on-screen key row) for those. Prefer the Send box when you want a permanent record of your intervention. Press Send (audited) (or press Enter) to submit.

Tip: For routine nudges you want your team to see — clarifying a requirement, redirecting the agent, or appending context — always use the Send box. Reserve direct terminal keystrokes for quick interactions where a record isn’t important.

Finished sessions

When a session ends, its terminal becomes unavailable. Navigating to a finished session — via View → on a task’s Workflow panel, or by turning on Include closed in the Sessions list — shows the session’s recorded summary:

• Agent — which agent template ran.
• Working on — which task the session was working, if any.
• Stage — which workflow stage it was activated for.
• State — its final state (see What the state badges mean above).
• Started and Ended — when it started and when it ended. For a session in the Lost state, the second row reads Lost at instead.
• Duration — how long it ran. Omitted for a Lost session, since it was never observed stopping.
• Exit code — how the process exited, when one was recorded.
• Reason — why the session ended; see Why a session ended below.
• Repo and Device — which repository it worked in and which machine hosted it.
• Cost — the total model spend this session incurred, with a smaller breakdown of generation spend versus cache-read spend, the number of turns, and the cache-hit percentage.

A task session’s page also carries a Skills section reporting whether each skill enabled for the workspace actually reached this session — see Skills for what each outcome means.

Why a session ended

A session records why it stopped, and CodeHerder shows that reason in three places: the Reason row above, the banner on a lost session’s page (which says so explicitly when no reason was recorded), and as the detail on the “session ended,” “session killed,” or “session connection lost” entries in a task’s Activity timeline and the workspace activity feed.

The reason is a short note describing what happened — for example, that the device running the session dropped off and missed its check-ins, that the device came back online without reporting the session it had been running, that the session was stopped while its device was offline, or that CodeHerder replaced a session that had stalled with a fresh one. The exact wording varies by case.

You don’t need to do anything for CodeHerder to recover: if a session’s stage is left without a live session, CodeHerder clears the dead sandbox on its own and the stage gets staffed again — which is why a task’s Workflow view can show more than one session for the same stage over its lifetime. The replacement session picks the stage up from where the work stands in the task’s sandbox. If a task still isn’t moving after that, see Why isn’t my task moving?.

What this session did

Every session page — live or finished — includes a What this session did section. This shows the meaningful actions the session took on its task, drawn from the event log: status advances, comments it posted, blockers it filed or resolved, and when it started and finished. The notes the session left as hand-off comments appear here too, giving you its own account of the work.

No chat transcript is stored — the event timeline is the durable record of what happened; see Activity feeds for how that record shows up on the task itself and around the workspace.

---

For the task list and its live-session indicators, see Finding and tracking your work. For agents that pause mid-run waiting on a human decision, see When an agent needs your input. For commenting on tasks and reading hand-off notes, see Collaborating. For understanding model spend across sessions, see Understanding costs. For sessions you create yourself, with no task behind them, see Interactive dev sessions. For a task’s sessions from the command line, see Agents and the CLI.