CodeHerderSearch⌘KRequest access →

Your sessions in the terminal

Run ch with no command to get a session sidebar, a Needs you sidebar and tabs. Open sessions and act on requests in the terminal.

Run ch on its own, with no verb, and it opens a session console right there in your terminal: a sidebar listing a workspace’s active sessions on the left, and a terminal you can type into on the right. A second sidebar, Needs you, sits at the far right edge and lists the decisions waiting on you. You can act on them without leaving the terminal.

ch

With no workspace named, the console opens on All: the active sessions of every workspace you can see, in one list. Pick a workspace to open it on with --workspace (or CH_WORKSPACE_ID):

ch --workspace acme/platform

When you get help instead

The console only opens in a real, interactive terminal. ch prints the usual getting-started summary and command list instead of the console when:

  • standard input or standard output is piped or redirected, rather than a terminal you’re typing into,
  • you pass --json,
  • you’re on a host other than macOS or Linux, or
  • you run ch --help — that always prints the full command surface, console or not.

This keeps scripts, CI jobs, and ch ... | jq pipelines working exactly as they always have — only a bare ch typed straight into a terminal opens the console.

The sidebar

The sidebar lists the active sessions in the current workspace, or in every workspace on All. Each row shows the session’s title — the task’s title if it has one, otherwise the sandbox’s title, otherwise the title the coding agent gives its own conversation — then its stage and the device it’s running on. A session you can’t attach to is not listed. The second line is in the harness’s colour. It names the harness, or on All the session’s workspace. Grouped By Device, your own machine’s sessions come first, from every workspace. The list refreshes on its own every five seconds, so you don’t need to reload anything to see a new session appear or an old one finish.

The top row of the sidebar says CodeHerder. On its right sit two small icons: the theme icon (◐ system, ☼ light, ☾ dark) and the menu icon ≡. Click the theme icon, or press t while the sidebar has focus, to cycle the theme. See Customize the terminal console.

Click Workspace at the top of the sidebar (or press Ctrl-B then w) to switch to a different workspace. It lists All first, then the workspaces that hold work, in alphabetical order — a group never appears here, because sessions run in a workspace. On All, a new session starts in the workspace of the highlighted session.

Resizing and collapsing the sidebar

Drag the divider between the sidebar and the tabs to resize it. The sidebar is at least 15 columns wide and at most half the terminal. Click « at the bottom right of the sidebar to collapse it to a thin strip. On the strip, ≡ opens the menu and » expands the sidebar again. Ctrl-B then [ collapses it, ] expands it, and - and + make it 2 columns narrower or wider. The console remembers the width and whether it was collapsed.

The Needs you sidebar

The sidebar on the right edge is Needs you. It lists the decisions you can make on your own work, the same items as Needs you on My work without Show team. That page explains each kind of item. The heading shows how many items you have.

Each row shows the task’s title. The line below it shows the kind of item and what it asks. The kinds are Question, Decision, Stage gate, Review, Network access, Settings approval and Marketplace approval. A kind the console does not know still appears, as Needs you.

In a single workspace, the list shows only that workspace’s items. On All, it shows every item, and each row adds a third line with its workspace. The list refreshes on its own, about once a minute and sooner when something changes. If there are more items than fit, a line at the bottom counts the ones above and below. A very long list stops at its first items and says Showing the first N.

Until the list loads, the sidebar says Loading…. With nothing to do, it says Nothing needs you. If the list can’t load, it says Could not load and why. With ch --local, there is no server to ask, so the sidebar says Needs you needs a CodeHerder server.

To use the list:

  • Press Ctrl-B then y. This expands the sidebar if it is collapsed and puts focus on the list.
  • Move with Up and Down (or j and k). PgUp and PgDn move a page. Home and End jump to the first and last item.
  • Press Enter to open the item in a tab. Esc gives focus back to your open tab, or to the session sidebar if no tab is open.
  • You can also click an item, or scroll the list with the mouse wheel.

Press Ctrl-B then { to collapse the sidebar to a thin strip, and } to expand it. Or click » at the bottom of the sidebar to collapse it, and « on the strip to expand it. On the strip, a number shows how many items wait (+ for more than nine). Drag the sidebar’s left edge to resize it. The width is at least 15 columns and at most half the terminal. The console remembers the width and whether the sidebar was collapsed.

The sidebar folds to its strip on its own when it would leave the tabs less than 40 columns. The console does not save that. Widen the terminal and the sidebar opens again. If you press Ctrl-B then y on a terminal that is too narrow, the status line says Widen the terminal to show Needs you.

To change the width, the collapsed state or the keys, see Customize the terminal console.

Acting on a Needs you item

Open an item with Enter or a click. It opens in a tab named for its kind. The tab shows what is asked, what happened, the task, its stage, its workspace and how long it has waited. Any options and comments appear below. Opening an item that is already open takes you to its tab.

Buttons sit in the tab’s header. The server decides what you may do, so you see only the buttons you are allowed to use. Every Needs you tab also has Open in browser (when the item has a task link) and Close. Open in browser copies the link. Ctrl+click it to open it.

Kind What you do
Question Step through the agent’s questions with Tab and Shift-Tab. For each one, pick an option with Space or Enter, or type your own text on the Other answer line. A question can allow more than one option. Answer every question, then click Submit answer.
Decision Pick one option and click Choose. An option that asks for an answer opens a field. Type your answer first. An option that cancels the task asks again: click Confirm cancel, or Cancel (or Esc) to go back.
Stage gate Click Approve to let the task move to the stage shown as Target stage. Click Reject to decline the move. Reject asks again: click Confirm reject, or Cancel (or Esc).
Review Click Open merge request to copy the merge request link. Ctrl+click the link in the tab to open it. Cancel wait ends the task’s wait for the review.
Network access Click Allow for session, Allow for workspace, Deny or Ask admins. Allow for workspace asks you to confirm. See Network access approvals for what each answer does.
Settings approval Click Approve (it asks you to confirm), Retry or Reject.
Marketplace approval Click Approve (it asks you to confirm), Reject or Revoke (it asks you to confirm).

If the console can’t read a question’s form, the tab says Answer this in the web app. Use Open in browser for it.

After an action, the status line says Done. and the item leaves the list. If someone else acted first, the status line says Already handled. If an item leaves the list while its tab is open, the tab says This no longer needs you. and the action buttons go away. If an action fails, the tab shows Could not complete with the reason, and you can try again.

Needs you tabs are not saved. When you run ch again, they do not reopen. The items are still in the sidebar.

The menu

Click ≡, or press Ctrl-B then m, to open the menu. It has:

  • settings opens the settings screen.
  • keybinds lists every key and where it came from.
  • reload config re-reads your settings and theme files.
  • update ready • appears only when a newer ch is ready. Choosing it installs that version and restarts ch.
  • detach quits the console and leaves every session running.

Filtering the sidebar

Press Ctrl-B then / — or just / while the sidebar has focus — to open a filter over the session list. Type a few words and CodeHerder narrows the list to sessions matching all of them: a session’s title, its task, its stage, its device, its repo, the agent running it, who started it, or what it was started for. The filter can also match up a session’s task ancestry. A parent task’s title then finds sessions running under its children. For that, group the list By Task or Filed by Me first; the next section covers grouping. The console starts grouped by device, where the filter matches each session’s own task instead.

Matching is fuzzy — the letters of what you type just need to show up in that order somewhere in a field, not all together — so “trm” matches “terminal” without you typing it in full.

While the field has focus, Ctrl-U clears what you’ve typed without leaving it. Press Tab to leave the field and move through the filtered list with the arrow keys, without losing the filter. Press Esc to clear it; if you’ve already left the field with Tab, the first Esc just clears the filter, and a second one moves focus to an open tab, if you have one.

Grouping the sidebar

Press Ctrl-B then g — or g while the sidebar has focus — to open a menu with four ways to group the session list: By Device, By Task, Filed by Me, and By Stage. Move the highlight with the arrow keys and pick a grouping with Enter or Space; Esc or g closes the menu without changing anything.

Sessions that don’t fit cleanly into a group — no task, no stage, or filed by someone else — collect in a group of their own that always sorts last. Under Filed by Me, sessions you started yourself with no task behind them gather in their own group just above that one.

With a group heading selected, Left and Right collapse and expand it, and Space toggles it either way.

Opening sessions as tabs

Click a session in the sidebar, or select it and press Enter, to open it in a tab — the same live terminal you’d get from ch session attach. Open several sessions this way and they stack as tabs across the top; switch between them with Tab / Shift-Tab, the number keys 1–4, or by clicking a tab directly. Every open tab keeps reading its session’s output in the background, even while you’re looking at a different one.

Each tab shows what its agent is doing. A working tab shows a spinner and how long it has been working. A tab waiting on a person shows ! and how long it has waited. If a tab that needs you is out of view, a ! Tab N badge appears beside + New, and the bottom bar says Tab N needs you. Click the badge to jump to it. When there are more tabs than the bar can show, a N more ▾ control appears after + New. Click it for a list of every open tab, and pick one with a click, or with the arrow keys and Enter. Drag a tab left or right to move it. To rename a session, right-click its tab and choose Rename, or click the name at the top of the tab details. The details open with the name in an edit field: type the new name and press Enter, or press Esc to keep the old one. A session without a task has one name. It starts as the name the harness gives the conversation, for example Codex’s thread name, and your rename replaces it. Whichever changed last wins, so renaming the conversation in the harness later renames the session again. Save an empty name to go back to the harness’s name. The same name shows on the tab, in the sidebar and in the web app. A session that belongs to a task is always named by its task and can’t be renamed. ch session rename does the same from the command line.

A header under the tab bar shows the open session’s state, harness, title, the folder it works in, stage, run time, and cost. On All it also names the session’s workspace. The title links to the session in the web app. Press Ctrl-B then i, or click the header, to open the tab’s full details. Press o there to go back to the terminal. The bottom bar shows the session’s cost and its task’s cost as Session: $… / Task: $….

Header buttons

The header also carries buttons for the tab you are in. Click one, or press its key. Each button shows its key. While the terminal has focus, keys go to the session, so the button shows the key you press after Ctrl-B. While a details, task or repos screen is open, the button shows the plain key.

  • Session tab: Task opens the session’s task. Details shows the session’s summary, and Terminal takes you back to the terminal. Repos opens the Repos screen. Next session appears once the task has a newer session. Stop appears only when you may stop the session. It asks first: click it, then click Confirm stop, or Cancel (or press Esc) to keep the session running.
  • Task tab: Attach to session appears when the task has a live session. Refresh reloads the task. Open in browser copies the task link — Ctrl+click the button to open it instead. Close closes the tab.
  • New-session tab: Close.

If you don’t want the buttons, turn off Show the tab header in the settings screen. That also hides the one-line facts above.

Closing a tab, or quitting the console entirely, only disconnects your terminal. The session itself keeps running on its device — reopen it later from the sidebar, or with ch session attach, right where it left off.

The console remembers your open session and task tabs, their order, and the tab you were in. The next time you run ch, it opens them again. It skips a session that has ended or that you may no longer attach to. A new-session tab is kept once its session has started. The list is kept in ~/.codeherder/tui-tabs.json, with a separate list for each profile and for --local. Close a tab to drop it from the list.

Task and session details

Click Task in the header, or right-click a tab or a session’s row in the sidebar and choose View task info, to open that task’s title, stage, type, priority, cost, description, custom fields, and comments in a tab of its own, alongside any terminal you already have open. If the task has a live session, the task tab shows it, and Attach to session (or n) opens it as a tab.

Once a session’s tab has finished, its menu adds Show tab details and Show terminal. They switch that tab between a plain-language summary of how the session went and the raw terminal it left behind. Press Ctrl-B then i for the summary, and o to go back. In a details, task or repos screen, press t to jump to the task behind the session, and n to open a newer session for the same task, once one has started. Press b on a task tab, or click Open in browser, to open the task in your browser.

Inside an info tab, arrow keys (or j/k) scroll a line at a time, PgUp/PgDn (or Space) scroll a page, Home/End (or g/G) jump to the top or bottom, r refreshes, and x closes the tab.

The Repos screen

Click Repos in a session’s header, or press Ctrl-B then p, to see which repos the session uses. The primary repo comes first. Each repo shows its name, whether it has changes, its folder, its branch, and any merge requests with their state. The screen is read-only: it cannot add or remove a repo. A session with no repo says so. Refresh reloads the list. Click Terminal or Details to go back.

Starting a new session

Click + New in the tab bar, or press Ctrl-B then n, to start a new session. This runs ch start in the same directory you launched ch from, opening it as a tab in the console. The tab shows the harness picker. Right-click a harness tile to set launch options, including the folder or workspace the session starts in. See Start a session in your own checkout for the picker, those options, and what the command needs.

Copying text from a session

Press Ctrl-B then c while a session’s terminal has focus to freeze that pane and enter copy mode. The session keeps running and producing output behind the scenes — only your view of it pauses. Copy mode isn’t available from a task or session’s info tab; switch to its terminal first.

Drag with the left mouse button to select text; letting go copies it to your clipboard right away. You can also press Enter or Ctrl-C (Cmd-C on a Mac keyboard) to copy the current selection and leave copy mode. Esc leaves copy mode without copying anything, and resizing your terminal window does the same.

Pasting an image into a remote session

When you’re attached to a session running on another device, you can send it an image — handy for sharing a screenshot with an agent. Which route you use depends on the machine you’re typing on.

On macOS, copy an image and press Cmd-V (Ctrl-V and Ctrl-Shift-V work too) to send it straight from your clipboard.

On Linux, paste the image’s file path instead. The console reads an image out of the clipboard on macOS only, so Ctrl-V on Linux goes through to the session as an ordinary keystroke. The file-path route works on macOS as well.

When you paste a path, give the full path from the root of your filesystem, like /home/you/shots/bug.png. A relative path pastes as ordinary text, and so does a path to anything that isn’t a PNG, JPEG, GIF, or WebP. A file over 8 MiB is refused with a message rather than sent.

Both routes only work for a session on another device. Paste into a session running on your own machine and you get plain text, like any other terminal. Esc cancels a transfer that’s still running.

Colors in a session

A session follows your console’s theme, including a session that runs on another device. The console sends your theme’s colors to the session, and a theme change recolors a running session at once.

Claude Code picks its own color theme only when it starts. ch starts it with a theme that uses your terminal’s palette, light or dark to match the console that started it. If you switch between a light and a dark theme later, a running Claude session keeps its old light or dark choice until you restart it.

A session that started before its device updated keeps its old look until you restart it. Restart it to pick up the new behavior.

Keyboard

Ctrl-B is the console’s prefix key — press it, then one of these:

Key Action
s Show sessions in the sidebar
w Show workspaces in the sidebar, to switch
n Start a new session (+)
c Freeze the current session and enter copy mode
g Open the grouping menu
/ Filter the sidebar
Tab / Shift-Tab (or Right / Left) Next / previous tab
1–4 Jump to that tab directly
x Close the current tab
r Refresh the sidebar now
q Detach and quit — your sessions keep running
? Show every key and where it came from
m Open the menu
, Open the settings screen
t Cycle the theme: system, light, dark
R Reload settings and theme files
[ / ] Collapse / expand the sidebar
y Focus the Needs you list
{ / } Collapse / expand the Needs you sidebar
- / + Make the sidebar narrower / wider
i Open the current tab’s details
T Open the current session’s task
p Open the session’s repos
N Open the task’s next session
S Stop the session — press twice to confirm
b Send a literal Ctrl-B through to the session, instead of triggering the console’s own prefix

While the sidebar has focus: plain arrow keys (or j/k) move the selection, PgUp/PgDn jump by a page, Enter opens the highlighted session or collapses and expands a group heading, w toggles the workspace picker, g opens the grouping menu, / opens the filter, Left/Right collapse and expand a group and Space toggles one, Tab moves focus to an open tab (if you have one), t cycles the theme, r reloads, n starts a new session, Esc clears the filter if one is set, otherwise leaves the workspace picker and, if you have a tab open, returns focus to it, and q (or Ctrl-C) quits.

While a details, task or repos screen is open, you press these keys without Ctrl-B: t opens the task, n the next session, p the repos, r refreshes, o goes back to the terminal or details, b copies the task link, x closes the tab, and S stops the session (press twice to confirm). Only the keys that apply to that screen work.

Every key can be remapped. See Customize the terminal console for how, and for each key’s setting name.

Mouse and scrollback

Click a session or workspace row to open or select it, click a tab to switch to it, and right-click a tab for a menu: Close tab, and — depending on what’s open in it — View task info, Show tab details or Show terminal, Open next session, and Stop and Close. A personal session you may stop or release also lists Stop sandbox and Release session. Right-click a session’s row in the sidebar for a shorter menu: View task info, and Stop session when the session allows it. Click + to start a new session. Scroll the mouse wheel over the sidebar to move through the list, or over a session’s terminal to scroll its output. Over the tab bar, the wheel moves you to the next or previous tab.

Hold Shift while scrolling to force the console’s own scrollback, even over a program that normally captures the mouse wheel itself — handy when the session you’re attached to is running something that would otherwise intercept scrolling. Scroll back down to the bottom to return to that session’s live output.

If the terminal is too small

The console needs at least 76 columns by 18 rows. Below that, it asks you to enlarge the terminal instead of trying to render a cramped layout. The Needs you sidebar folds to its strip before then. See The Needs you sidebar.

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