Your sessions 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.

ch

Pick a workspace to open it on with --workspace:

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. Each row shows the session’s title, then its stage and the device it’s running on — and a session you can’t currently attach to is marked unavailable. 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.

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

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.

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.

Task and session details

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.

Once a session’s tab has finished, its menu adds Toggle terminal output, switching that tab between a plain-language summary of how the session went and the raw terminal it left behind — press o for the same toggle without opening the menu. From either view, 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.

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.

Starting a new session

Click + 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 — see Start a session in your own checkout for what that command does and what it 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.

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	Quit the console
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), 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.

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, Toggle terminal output, Open next session, and Stop and Close. 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.

Related guides

• Start a session in your own checkout — what + runs, and what it needs to succeed
• Sessions from the command line — find, read, and steer a session outside the console
• Following a live agent session — the same live terminal, from the web app
• Using the ch CLI — the conventions the rest of the CLI follows