CodeHerderSearch⌘KRequest access →

Following a live agent session

Watch an agent session live, tell a stuck one from a busy one, send input, and review what a finished one did.

When an agent picks up a task, CodeHerder spawns a clean session for it and starts a terminal process on an eligible device. The Sessions view shows what is running now. You can watch progress, step in when needed, and review what a finished session did.

The Sessions sidebar view

Sessions appears in the sidebar of every workspace. The number next to it counts the sessions running right now. It updates as agents start and finish work.

Click Sessions to open the full page. If you can start work in the workspace, a New session button sits in the page header. See Start a session on a device.

Below the header is a filter bar, then the session list. A shorter list, Sessions needing attention, appears above the session list. It shows up only when CodeHerder has flagged something.

The search box in the filter bar narrows both lists. It matches the task title, agent, repo, device, state and ID.

Sessions needing attention

This list shows live sessions that CodeHerder has flagged as stale. A flagged session can be one the session list can’t show: it is still running after its sandbox finished. See When a session goes quiet for why that happens.

The list stays hidden while nothing is flagged. It appears as soon as CodeHerder flags a session.

Column What it shows
Session The session itself. Click through to its page.
State The session’s state badge, plus a warning badge that names why CodeHerder flagged it.
Agent The agent running the session.
Device The device the session runs on.
Last contact When the device last reported in. Only a flagged row has a value.

Click the Agent or Device header to sort. The Running / Open / All switch in the filter bar doesn’t change this list. That switch belongs to the session list below.

The session list

The session list has its own heading, and the heading follows the filter. Each row is a sandbox: the durable workspace where an agent works on a task, or where you work in a session you started yourself. A sandbox can hold more than one run over its life. An agent’s process can restart in the same sandbox, so one row can stand for several runs.

The Running / Open / All switch picks what the list shows. Running is the default.

Heading Switch What it shows
Sessions running now Running Sandboxes with an active terminal right now.
All open sessions Open Every sandbox that hasn’t finished, running or not.
All sessions All Every sandbox, including finished ones.

When you pick Open or All, the subtitle also says how many are running.

The list loads a batch at a time. Use Load more at the bottom to get the next batch. You can keep going until you reach every row that matches your filters.

Column What it shows
Working on For a task, the task title and the task’s current stage. For a session without a task, its title or branch name, with the base branch underneath.
Type For a task, the task’s type badge (for example story or bug), or Task if the type isn’t known. For a session you start on a device, Remote. For a session started from your own checkout with ch start, Local.
State The sandbox’s own lifecycle state. When the sandbox isn’t running, a second badge follows a Last session label and shows how the last run ended. See Sandbox state vs. a run’s outcome.
Agent The agent running, or last running, in this sandbox.
Device The device the sandbox runs on.
Repo The repository the sandbox’s isolated worktree comes from.
Cost The model spend for this sandbox. A task row also shows (task $X) under it: the spend across every sandbox of that task. A session without a task shows a dash.
Created When the sandbox was created.
Actions The controls you can use on this row. See below.

Click the Agent, Device, Cost or Created header to sort. See Sorting a list. On a narrow screen, some columns fold under the title.

Actions depends on the row:

  • A running row has Drop in. It opens the live terminal.
  • A row that isn’t running has View run, or N runs when the sandbox has held more than one. It opens the latest run’s page.
  • A finished row also shows when it finished.
  • Any row can show Start (Resume for a stopped session) and a More menu. They hold only the actions you may use. See Retiring a leftover session.

Sandbox state vs. a run’s outcome

A sandbox’s State badge and a run’s outcome answer two different questions. The list shows both.

  • Sandbox state is the sandbox’s own lifecycle. A task’s sandbox moves through Provision, Ready, Active, Completing and Done. A sandbox you start yourself can read Stopped. See Start a session on a device. Done is the only end state. It says the sandbox is finished, not whether the run inside finished its work.

  • A run’s outcome is CodeHerder’s answer to “did this run finish its work?”. It is the badge after Last session. It also appears wherever one session is shown: the session’s own page, a task’s Workflow rows, and the session lists on a device, repo and agent page.

    Badge What it means What usually causes it
    Starting The session is being set up. None.
    Running The session is live right now. None.
    Completed The work was handed off. The task’s stage advanced, or you used Mark done.
    Released The session was stopped on purpose before it finished. It is not a failure. Stop, Release, a spend cap, a session you started that was stopped or idle-parked, an AWS Spot reclaim on a cloud device (see If AWS reclaims the instance), or CodeHerder clearing a session whose stage had moved on.
    Incomplete The agent’s process ended on its own without handing the stage off. None.
    Failed The process ended badly. A non-zero exit without handing off, a stalled session CodeHerder replaced, or a session that failed to start.
    Lost Contact with the device or the process was lost. The device stopped reporting, its connection dropped, or the session’s sandbox had already retired. See When a session goes quiet.

    Hover a badge for a one-line explanation. For how the outcome differs from the Reason row, see Why a session ended.

The green dot means the same thing everywhere: an agent process is running right now.

Queued and leftover sessions

Two badges can appear above the session list, even with Running selected. They count sandboxes that have no running terminal, so the default view would otherwise hide them.

N queued for a slot means sessions are set up and waiting for a device slot. Each device runs only so many sessions at once. See Concurrency and capacity. A queued session starts by itself when a running session on that device finishes. If this count is high or keeps growing, it often explains why a new task hasn’t started. See Why isn’t my task moving?.

N live on finished tasks is a warning. It counts sessions that are still open although their task finished, was cancelled or was abandoned. Such a session does no useful work. It only holds a sandbox slot that another task could use. The same row also shows a warning badge with the task’s stage, for example Task Done.

The “N stale” badge in the page header is a different count. It watches for a different problem, in Sessions needing attention. See When a session goes quiet.

When a session goes quiet

CodeHerder watches every live session for two warning signs. When it sees one, it flags the session in Sessions needing attention.

  • Device silent: the session’s device hasn’t reported in for about fifteen minutes.
  • Sandbox retired: the session is still running, but its sandbox has finished.

A brand-new session gets the same fifteen minutes before the first check can flag it. Sandbox retired has its own five-minute grace period, so a normal teardown never trips it.

A flagged row shows a warning badge next to its state. Its Last contact column shows when the device last reported in. The page header shows a warning badge reading “N stale” while at least one live session is flagged.

A flag is a warning, not a verdict. CodeHerder rechecks every live session about every thirty seconds. It marks a session that is still flagged as Lost. A Device silent flag clears by itself if the device reports in before the next check, so a flagged session doesn’t always end up Lost. A Sandbox retired flag doesn’t clear this way. That check doesn’t look at whether the device is connected. A session is also marked Lost soon after its device’s connection drops, usually within two minutes.

Marking a session Lost fires the session.lost webhook if your workspace has one. See Webhooks.

You don’t need to act when a session goes Lost. CodeHerder recovers by itself. See Why a session ended.

Is this session making progress?

A session can be live and still do nothing useful. To tell a busy session from a stuck one, open its page and find the Progress row in the Progress and cost panel. The row shows only while the session is live. It reads like active (recent progress) or stalled at child output (tool open silent). The session lists don’t show it.

The first word is the verdict:

Verdict What it means
active In the last two minutes, the session printed output, wrote to its transcript, or ran a tool.
idle The session has been quiet for longer, but nothing looks wrong. The agent may be thinking, or waiting for you.
stalled Something that should have finished hasn’t. The reason says what.
unknown CodeHerder can’t tell. The device hasn’t reported on the session recently.

For a stalled session, the reason says what is stuck:

Reason What it means What to try
tool open silent The agent started a tool and nothing has come back for five minutes. Look at the terminal, or run ch session tail. A long build or test run can look like this.
input unanswered Someone typed into the session and the agent hasn’t reacted for five minutes. Check the terminal. The agent may be at a prompt that needs a different answer.
edge lag The agent’s output stopped on its way to your viewers for 30 seconds. The row names where it stopped, for example supervisor frame or fan out. The agent may be fine and the connection may be the problem. Open the terminal to see what the agent is doing.

An unknown session has one of three reasons: no report (the device has sent nothing), report stale (the last report is more than 90 seconds old), or unreadable report. Check that the device is online. Update it if it runs an old version. See Managing your devices.

A stalled verdict only observes. It never stops, restarts or flags a session, and it doesn’t lead to Lost. The warnings in When a session goes quiet work differently. They flag a session in Sessions needing attention, and CodeHerder can then mark it Lost. If a stalled session is truly stuck, stop it yourself. To stop it without losing anything, see Stop and keep the work.

ch session show prints the same verdict on a progress: row. See Sessions from the command line.

Retiring a leftover session

Open the leftover session’s task and find the Sessions panel on its detail page. The panel hides spawn attempts that never started unless you switch on Never-started attempts. These controls appear there, and on a session list row, when you may use them:

  • Launch session appears when the task has no live session. It sets up a fresh session for the task’s current stage.
  • Start appears on a session that is set up but not running. It brings the terminal online. Only a workspace admin or owner can use it on a task’s session. A stopped session you started yourself shows Resume instead.
  • Finish session wraps up a session that is actively working. It moves the session toward a normal close instead of cutting it off. Only a workspace admin or owner can use it.
  • Mark done appears once a session is in that closing state, usually right after Finish session. It closes the session for good. It stops the agent process if one is still attached, and it frees the slot. The run ends Completed.
  • Release ends the session at once, without merging anything. A confirmation asks first. On a task’s running session, the task keeps its sandbox and folder, and the next run reuses them. A sandbox that isn’t running moves to Done and can’t be resumed. The run ends Released, a deliberate stop and not a failure.
  • Stop appears on a session you started without a task. It stops the sandbox so you can resume it later. The run ends Released.

A workspace admin or owner can use Mark done, Release and Stop. So can the person who operates the session’s agent, meaning the human who created that agent.

CodeHerder shows only the controls you may use. If Release is missing, ask an admin, an owner or the agent’s operator to retire the session. See Why a control is missing.

If a device looks full but nothing seems to run on it, the cause is usually leftover worktree slots, not a leftover session. See Reclaiming stuck worktree slots.

Reaching a session from a task

A task’s detail page has a Workflow panel. It lists the sessions that ran each stage. Each session shows Drop in if you may join it live, or View if you may not. A finished session always shows View. View opens the session’s page with its recorded summary.

While a session is live, the task’s page header, the task’s card on the Board and Graph views, and the task’s row in the Tasks list also show Drop in.

The live-terminal page

Drop in opens the session’s page and connects your browser to the agent’s running terminal.

Who can drop in

Opening the terminal, using the Send box and reading scrollback need a human who is a workspace owner or admin, or the operator of the session’s agent. The operator is the human who created the agent. Stop needs the same standing. Agents can’t attach to a session.

There is one exception. You can start a session as yourself instead of as an agent. On that session, only you can type or attach. An admin can still read its output and stop it.

Without access, the header shows No terminal access. A notice says who can attach. The page doesn’t retry.

The connection badge

The page header shows a badge next to the state badge:

Badge Meaning
Connecting… Opening the connection for the first time.
Connected The terminal is live and receiving output.
Reconnecting (attempt N) The connection dropped. The page retries by itself and counts each attempt.
Session completed, Session released, Session incomplete, Session failed, Session lost The session has ended. The outcome is the one in Sandbox state vs. a run’s outcome. You can’t attach to it any more. A banner explains what happened. For a lost session, the banner gives the reason if one was recorded.
Rejected: … CodeHerder couldn’t open the connection. The badge names the cause, for example Rejected: auth expired. Sign in again and reopen the session.
No terminal access You can’t attach. See Who can drop in.

While the session is live and you may stop it, a Stop button sits in the page header. It asks you to confirm, then sends a stop signal to the agent’s terminal process. Use it to halt a session that is going off track. Stop doesn’t save text you typed but didn’t send. To keep that text and push the work first, run ch session stop --preserve. See Stop and keep the work. The button disappears when the session finishes. A session you stop ends Released, not failed.

If you can watch but can’t type, a note above the terminal reads Observe-only terminal. That happens, for example, while a session is still starting.

On a phone, an on-screen key row below the terminal has Esc, Tab, ⇧Tab and the four arrow keys. It lets you answer an agent’s prompts without a keyboard. If you navigate by keyboard, press Ctrl+Shift+Space and then Tab to move focus out of the terminal.

Tip: If clicking or scrolling in the terminal does nothing, a full-screen program has probably captured the mouse. Hold Shift while you click or scroll to use the terminal’s own scrollback and selection.

Sending input to a live session

You can send input two ways. They differ in what the team’s audit trail records.

Typing in the terminal sends keystrokes straight to the agent’s process. This is fast, but the team activity feed does not record it. A banner above the terminal says so while the session is live. Keys from the phone key row are not recorded either. You can also paste an image from your clipboard into the terminal with Ctrl+V (⌘V on a Mac). PNG, JPEG, GIF and WebP images up to 8 MiB work. CodeHerder doesn’t record pasted images.

The Send box sits below the terminal. It sends text through CodeHerder, and the activity feed records it, so the team can see what you sent and when. Use it for nudges your team should see, such as a clarified requirement or a change of direction. It appears only while the session is running, and only if you may type into the session.

Press Send input (audited), or press Ctrl+Enter (⌘+Enter on a Mac). Enter alone adds a new line. Newlines and tabs in your text arrive as typed. After your text, CodeHerder presses Enter in the terminal, so the agent receives a submitted line. The Send box can’t send Escape or other control keys. Use the terminal for those.

The same Send box appears when you expand a live session’s row on an agent’s page, for people who may send input.

The CLI has the same function. ch session input sends text. ch session ask sends text and waits for the agent’s reply. See Sessions from the command line.

Finished sessions

When a session ends, its terminal is gone. Open a finished session to see its recorded summary. Reach it from View on a task’s Workflow panel, or from View run on a row in the session list.

The top of the page lists:

  • Agent: which agent ran. A badge shows the session’s purpose when it isn’t plain work.
  • Working on: the task the session worked on, if any.
  • Repo and Device: which repository it worked in and which machine hosted it.
  • Stage: the workflow stage it started for.
  • Started: when it started.

The state and outcome badges are in the page header.

The Outcome and cost panel lists:

  • Ended: when it ended. For a Lost session the row reads Lost at instead.
  • Duration: how long it ran. A Lost session has none, because nobody saw it stop.
  • Exit code: how the process exited, when one was recorded.
  • Reason: why the session ended. See Why a session ended.
  • Cost: the model spend of this session, with a breakdown, the number of turns and the cache-hit percentage.

While the session is live, the same panel is called Progress and cost. It shows the Progress row and the spend so far.

A finished session’s page also has a Saved output panel, above the Outcome and cost panel. It shows what the run printed before it ended. A search box narrows it to matching lines. Each match keeps its line number from the full capture. The Wrap button toggles line wrapping. If the run printed nothing, or CodeHerder already released the capture, the panel says so. Only the agent’s operator or a workspace admin can read it. ch session tail shows the same text. See Sessions from the command line.

When CodeHerder recorded which skills it delivered to a session, the page also shows a Skills section. It says whether each skill enabled for the workspace reached the session. See Skills for what each result means.

Why a session ended

The outcome badge and the Reason row answer two different questions. The outcome is the classification: completed, released, incomplete, failed or lost. The Reason is a short note that says what happened, when CodeHerder recorded one.

CodeHerder shows the reason in three places: the Reason row, the banner on a lost session’s page, and the detail on the “session ended”, “session killed” and “session connection lost” entries in a task’s Activity timeline and the workspace activity feed. The banner says so when no reason was recorded.

Typical reasons: the device dropped off and missed its check-ins, the device came back without reporting the session it had been running, the session was stopped while its device was offline, or CodeHerder replaced a session that had stalled. The exact wording varies.

One label looks like it disagrees with the badge. The activity timeline calls an operator’s Stop “session killed”, but the session’s badge reads Released. Both describe the same event. “Killed” is what happened to the process. “Released” is how CodeHerder classifies the outcome.

You don’t need to do anything for CodeHerder to recover. If a stage is left without a live session, CodeHerder clears the dead sandbox and staffs the stage again. That is why a task’s Workflow view can show more than one session for the same stage. The replacement session picks up from where the work stands in the sandbox. If a task still isn’t moving, see Why isn’t my task moving?.

What this session did

A session that worked on a task has a What this session did section, live or finished. It lists the meaningful actions the session took on its task, from the event log: status changes, comments it posted, blockers it filed or resolved, and when it started and finished. The hand-off notes the session left appear too, as its own account of the work.

By default CodeHerder stores no chat transcript, and the event timeline is the durable record. A workspace can opt in to stored session transcripts. When it does, the session page also has a Transcript section. See also Activity feeds.


For the task list and its live-session indicators, see Finding and tracking your work. For agents that pause mid-run to wait on a human decision, see When an agent needs your input. For commenting on tasks and reading hand-off notes, see Collaborating. For model spend across sessions, see Understanding costs. For sessions you create yourself with no task, see Start a session on a device. For finding, watching and steering a session from the command line, see Sessions from the command line.

Last updated

Try it on one repository for two weeks.

File a task. An agent builds it. A person reads every request. You see the cost of each task.

Try "pricing", "connect a device", or "who reviews the code"

↑↓ move · ↵ open · esc close