Core concepts

The interface

Everything in the dashboard hangs off four surfaces: the sidebar that lists your work, the board that shows its state, the transcript you read, and the composer you drive it from.

Try the interactive demo

The homepage films show Terminals and a day with Termdeck. Select Watch the film to start, use the timeline to seek, or expand to fullscreen. The films start muted and need no sound. With the player focused, press K to play or pause, M to toggle sound, F for fullscreen, or the left and right arrow keys to skip five seconds. Closing the demo pauses playback.

The demo workspace includes conversations about debugging duplicate charges, reviewing pagination, profiling search, keyboard accessibility, webhook regression tests, and designing an export API. Each has several exchanges with findings, tool output, and verification details. Live examples continue through follow-up work, alongside the approval, plan, question, sub-agent, and terminal chats.

Responses arrive in smaller bursts with pauses between sentences and tool calls. New chats stream their first reply too. Send a prompt about one of those topics to see a longer scripted example, or stop a response with the composer controls. All demo commands, measurements, and replies are local fixtures: no coding CLI runs and no external model is called. Refreshing restores the example workspace.

The demo's Settings works on a sample account with three machines. You can add, rename, update and remove machines, sign in to and switch between Claude and Codex accounts, run health checks, pick a plan, turn on push, and edit approval rules. It is all simulated in your browser: a new machine connects by itself, checkout skips the payment page, nothing is charged, and no notification is sent. Your changes last until you close the tab.

Command palette

Press Ctrl K (or Cmd K on a Mac) to search chats by title, project, or machine. It lists chats in the projects you have added, the same ones the sidebar shows, and each chat row names its project and machine. The palette also opens pages and each machine's own page in Settings, and offers actions for the current chat, including its files, session id, and Stop while a turn is running. Use the arrow keys and Enter to choose, or Escape to return to where you were. In the docs, the same shortcut still focuses docs search.

The sidebar is the primary navigation at every screen size. On a phone it becomes a drawer rather than disappearing.

At the top, beside the Termdeck name, the magnifier opens the chat filter and the panel button hides the sidebar. Under them is one row of icons: Home, Approvals, Terminals and New chat, the outlined one at the end. Point at an icon to see its name. On a phone the row has no Terminals. Below is the chat list. At the bottom, a Usage line, then your name over your plan, the bug button (report a bug or suggest an idea), the bell and Settings. Clicking your name opens Settings too. There is no bar across the top of the app on a desktop: the sidebar and the top of the page you are on hold everything. Usage and Archived chats are sections of Settings.

The Usage line shows each engine's mark and how full its fullest usage window is, in amber and then red as it fills. Point at a mark for every window and when each resets. Click the line to open the Usage section above it, which checks again and lists every window for every engine as a bar: how full it is, how far over or under pace you are (the thin mark shows how much of the window has passed), and when it resets. The section folds itself away a moment after you move off it or click elsewhere. To keep it open, click its pin; it then stays open across reloads until you click the line again. If a window gets close to its cap, the section opens by itself once so you notice. For Claude and Codex, a ↺ pill beside the engine name inside the expanded section shows how many one-off limit resets remain, when available; see Live rate limits. It shows its last reading the moment the page opens, then checks for fresh numbers; if a check fails or the provider is busy, the last reading stays on screen. Signing out removes the saved reading from the browser. To hide the line, turn off Show usage limits in Settings, then Appearance. Every window, for every engine, is in Settings, then Usage, under Engine limits; see Live rate limits.

Chats appear in the sidebar only for folders you have added. That is deliberate: a machine may hold hundreds of project folders and you probably care about six. Add and remove them in Settings, then Projects: Add folder, beside the Your projects heading, picks any folder on a machine, even one with no chats yet, and Available folders below lists folders that already hold chats, each with Add. Scratch, /tmp and worktree folders are kept out of that list, behind Temporary and worktree folders at the bottom of the page. A project stays on your list after its last chat is gone, whether you deleted the chats or the CLI cleared out old ones, as long as its folder is still on the machine. Starting a chat in a folder adds it too, so with a machine connected and no projects yet, the sidebar offers New chat, where you pick the folder for your first chat. Chats running in a git worktree are folded into the base repository rather than showing up as a separate project you never added, including a chat that moves itself into a worktree in a folder beside the repository, and starting a chat inside a worktree adds that repository to your list rather than the worktree.

Starter has 2 projects and Pro has as many as you like. On Starter, adding a third opens an upgrade prompt; remove one in Settings, then Projects (its ⋯ menu, then Remove) to make room. Starting a chat in a folder you have not added adds it, so on Starter that chat stays out of the sidebar until you have room.

Your projects lists every folder you have added, whether or not its chats can be shown right now. A folder whose machine is offline, whose machine is no longer on your account, or that has no chats on that machine any more still gets a row, with a short line saying which of those it is, so you can rename it or remove it instead of wondering where it went. Each row shows the project's name, its folder and the machine it is on; its ⋯ menu holds Rename, Show hidden files (lets the file viewer list dotfiles such as .env and key files for that project; off by default, and the row says when it is on) and Remove, which asks first. Removing a project keeps its chats on disk. The list is your account's, not one machine's, so it looks the same on your phone and your laptop. A project you add, or a chat you pin, rename or archive, on one device shows up in every other open tab within a second, without a reload.

Ctrl B collapses the sidebar on desktop and opens the drawer on a phone. While the sidebar is hidden, the panel button at the top left of the page brings it back, so the shortcut is a convenience rather than the only way. Drag the right edge to resize it, or double click that edge to reset.

Reading a chat row

Each row has two lines. The first is the chat's state, its title, and how long since you last wrote in it, short as in 2h or now. Point at the time for the exact moment. The second is the icon of the machine the chat is on, the project's name and the logo of the chat's engine. A CLI icon beside the engine logo means the chat is driven outside Termdeck. Point at the machine icon for its name, at the project for its folder, and at the engine logo for the engine and chat status. An amber dot means the chat is working; the engine logo takes the place of the Working text. Other statuses still appear in words: Active (something outside Termdeck is writing to the chat), Needs you, Failed, Finished, Stopped, Unknown or Draft. Point at the word for details. A red dot means the chat needs you; a chat at rest shows no dot and no status word. A row with ⌁ and a number has that many background shells running. The state comes from what the transcript and the live stream say, and the same reading drives Home, the tab title count and the notification list, so those can never disagree with each other.

Rest on a row for a card that names the chat's folder, its machine, its branch and its model in full, with its state in words. The machine wears its mark: the icon and colour you gave it under Settings, then Machines & accounts. The row and the card mark the folder with a warning when that folder is no longer on the machine, which is what you see after a project has been moved or deleted, and the card gives the machine's own reason. A folder Termdeck could not check, because the machine is asleep or the check timed out, is left unmarked rather than accused.

The order chats are in

Chats are listed by when you last sent a message, and that is the same rule on Claude, Codex and Grok. An agent writing files for an hour does not pull its chat back to the top, and a chat you replied to a minute ago does not sink below one you have not touched since breakfast. The time printed on the row is that same moment, so where a row sits and what it says always agree.

Some transcripts grow too large for Termdeck to find your last message in, which is common for a Codex chat full of images. Those rows fall back to a message near the start of the chat, usually the one that opened it, so they can sit lower than they belong but never above a chat you spoke to more recently. A row with no usable time at all reads Time unknown.

The list starts with the newest 200 chats on each machine, which keeps it fast to open. When you reach the end and a machine has older chats in your projects, the last row is Load older chats: click it for the next 50 from each machine, as many times as you like. Older chats you have loaded stay in the list until you reload the page.

Nothing overrides that order, and running is not an exception. A forty minute agent run does not lift its chat above one you spoke to a minute ago. Which chats are working is shown by the amber dot on the row and grouped properly on Home, which exists for that question.

Three groups sit above the list. Pinned is your own choice of what stays at the top: pin a chat from its row's menu, and Alt 1 to Alt 9 open the first nine pinned chats from anywhere, with a draft you were typing kept. Needs you is a turn stopped on an approval only you can give, so its position is the notification. A chat waiting on your approval shows here even when its folder is not one of your projects, so the count on the bell always points at a row you can open. Active is a window over the same clock the list is sorted by: at its default of 15 minutes it holds every chat you have sent to in the last 15 minutes. Change the width, or switch it off, under Settings, then Chats. A chat with a background shell still running, such as a dev server, stays in Active for as long as the shell runs, whatever the window and even with it switched off. Each group has a heading.

Under the groups, the rest of your chats are gathered under their project's name, with the machine beside it when you have more than one. Each project sits where its newest chat falls in the time order, and its chats stay newest first, so the grouping never changes which chats are near the top.

Because Active reads the same time as the sort, it groups the top of the list and can never reorder it. Widening it, narrowing it or switching it off moves chats in or out of the group, never up or down the list.

A chat being driven from outside Termdeck says Driven outside Termdeck on its card, and that means the same thing on every engine: a Claude CLI holding the transcript, or a Codex rollout another client is writing. Its composer stays locked while that lasts, because two writers on one transcript fork it.

Use the arrow keys to move through an action menu. Right arrow opens a submenu; Left arrow or Escape returns to its parent. Escape closes the menu and returns focus to its opening control. On touchscreens, tap a submenu to open it.

Right click a row for its actions: open, pin, rename, start a new chat with the same settings, duplicate (on engines that can fork a chat), archive, export as Markdown or plain text, project instructions, recap, copy a link to the chat, copy the session id, copy the folder path, and delete. While a chat is running the menu also offers Stop run, a view only chat offers Take over, and Permission mode changes the mode for that chat. A Claude Code chat that is open also lists its run options.

Home

Home is the board: every chat across every machine and every engine, grouped by run state rather than by project. A chat with a background shell still running is grouped with the working chats until the shell ends. This is the view for the question "what is happening right now", when the answer spans a laptop, a desktop, and a build VM.

Each chat is one line in its group: a dot for its state (red when it needs you, an amber dot while it works, green when it is done), the title, the project (and the machine, when you have more than one) and how long since you last wrote in it. On a phone the project moves under the title.

The bar across the top names the page and counts what needs you, what is working, and how many chats and machines there are. It holds the filter, which matches on prompt text, project, and machine at once, then Select, which lets you act on several chats together and is the fastest way to archive a week of finished work, and Show archived.

When no machine you have can run a turn, a card above the list says which of three things is missing and prints the command that fixes it: no CLI installed, a CLI that was never signed in, or a saved login the provider has since refused. A machine is only counted out when it says so itself, so a check that merely timed out is never reported as a machine that cannot work.

Under it, a line totals the cost and tokens of chats that finished since you last opened them, marked in chats you have not reopened. Opening a chat takes its share off the line. Point at it for what counts.

A row's status dot shows what the chat is doing now and is separate from its time, which is when you last sent a message. Hover the dot for details. Pinned chats keep their pinned placement whatever they are doing. Open the chat for its current run status: visible response or tool progress advances Starting to Responding even if the provider's start signal arrives late.

The Sub-agents panel keeps its current rows and count visible while it checks for updates. Its loading state is reserved for the first answer. If a later check fails, the last result remains visible with an update warning; if the first check fails, the panel reports that it is unavailable instead of claiming there are no agents. On an idle Codex chat, the Sub-agents tab shows no count while the dock is on Files. Codex keeps no list of a chat's sub-agents, so finding them means checking every Codex chat on the machine. That check runs when you open the tab, when a turn runs, or when the chat starts a sub-agent.

While a Codex turn runs, its sub-agents show live like Claude's: in the tray above the message box, and in the panel with the command each one is running, its tokens and tool calls so far, and the first line of its answer when it finishes. A Codex sub-agent's card is named by its task, and its type is the name Codex gave it, the same name its rows in the transcript use. It has no Stop of its own: the turn's Stop stops its sub-agents too.

Each sub-agent card has a status glyph and label beside its type. The arc means it is running; a check means it finished. The card says how the agent ended: complete, failed, or stopped. An agent you stopped, from its card or with the turn's Stop, reads stopped in the same grey as a finished one, never in the failure red, and its row in the transcript does the same. The time on a card is how long the agent has actually been working, counting up while it runs. When the chat sends a message to an agent that already finished, the agent picks up on its original card: it goes back to running, gets its Stop again, and its time adds the new run to the old one. The message row in the transcript names the agent the way the panel does.

The transcript

The transcript is the chat itself, rendered from the engine's own records with the live stream layered on top. Your messages sit on the right in a soft bubble; replies read as plain text, with each run of tool work folded into one quiet card.

  • Tool calls fold up into one line each with a summary of what they did, and open on click. A command shows the command it ran, colored like a terminal, and only once: when the row already shows it in full, opening the row goes straight to its output. A file edit shows its diff with how many lines it added and removed, on every engine, with line numbers once the edit has landed and a new file tag on a file it created. A Codex patch takes its line numbers from the change Codex records for each file, so a file with no such record, or one that does not match the patch, shows its lines unnumbered. The card's own added and removed totals add up the rows inside it. An edit that replaced every occurrence of a string says how many places it changed. A file read says which lines it read in its row, for example lines 10-17 of 29, and shows them numbered and colored; an image it read shows large, with its name and an Open full size button. A search through grep or rg lists its matches under each file with their line numbers. A Codex patch that touches several files names each one above its lines. Long output, long diffs and long files show their first lines and a Show all N lines button that opens the rest in place, so the chat is the only thing you scroll. A web search shows what it searched for and how many pages it found; open it for each page's title and site as a link, then the agent's summary of what it read. A page the agent fetched names the site on its line and opens on what it asked of the page and what came back. The one line summary counts files read and searches separately from other commands, including on Codex, which reads and searches through its shell.
  • Plans read as Proposed a plan with the plan's title and what you decided: Approved, Kept planning, Changes requested with your words under it, or Not answered when the request was withdrawn before you answered. Open the row to read the plan. The file the agent saved the plan to is named there rather than shown as a separate edit.
  • A sub agent's row gives its task, its type, how many tool calls it made and the first line of its answer. Open it for the whole answer, the prompt it was given behind Prompt, and Open in Sub-agents for its card and its own transcript. One running in the background says so until its answer arrives. On Codex the rows that start an agent and wait for one name it, and open on the same Open in Sub-agents button.
  • Background commands are named by their command when the agent checks on one or stops it: Read output of npm run dev, Stopped npm run dev.
  • Skills and tools: a skill's row names the skill with its description under it. A tool from an MCP server opens on its arguments as a table, with long values cut short behind Show all, and its result as a table, text or an image. Bookkeeping the engine does for itself, such as loading a tool before using it, is one quiet line.
  • Permission requests render as cards with Allow and Deny, a risk level, and the exact command or path in question.
  • Plans and questions get their own cards, because they need a decision rather than an approval.
  • Sub agents appear in the right hand dock: what is running, what finished, and what it is currently doing. Open a row to read the delegated task and the agent's own transcript. The transcript is read when you open the agent and again when it finishes; while it is still running, press Refresh above it to catch up. Its status, activity and counts stay live either way.
  • Retries are named. A turn that stalls because the provider returned a retryable error says "retrying" rather than sitting silent, which is the difference between a slow run and a stuck one.

One row under each turn says how long the turn worked, then holds Copy (the reply), Restore files (when the turn edited files: puts them back as they were before the turn, after you confirm) and Branch (a new chat holding the conversation up to the end of that turn). Restore files and Branch are on Claude chats; a Codex turn keeps its own two controls. The newest turn always shows them; an older one shows them when you point at it or at its reply, and on a touch screen they are always shown. See Checkpoint restore and Branch from here.

The top of a chat

There is no bar above a chat: its own header is the top of the page. It holds the engine's mark, the chat's title and its project (and the machine, when you have more than one), a ring that fills as the context window does, and, when the folder has uncommitted changes, a button saying how many files changed and how many lines were added and removed, which opens Files & agents. Then come ⋯ (more actions) and the Files & agents button. The chat's model, branch, pull request, account and sub agent count are listed at the top of the ⋯ menu.

The ring shows how much of the model's window the conversation is using, and turns warm as the chat nears the point where the engine compacts. Click it for the breakdown of what is filling the window, and for the Compact button when it is getting full. Until a chat has finished a turn there is no count to show, and it says "no reading yet" rather than disappearing.

The composer

The composer is where you send prompts and where every per chat control lives. It is one card under the conversation: the message box, then the + button and two chips beside it. The model chip names the model and thinking level and opens the model, thinking and context window settings. The mode chip shows the permission mode and opens permissions, Termdeck rules and Build or Plan; it turns red on Full access.

ControlWhat it does
ModelIn the model chip. Picks the model for this chat, from the catalog the CLI itself reports. Each row shows the exact model name it will run, the usable context window, the model's available thinking range, and any optional speed tier the catalog advertises. Rows name their engine only under the ★ favourites tab, the one list that can mix engines. Claude models that can run on a 1M window are listed and run on it only; see Claude's 1M context window. An empty list means the CLI could not answer, which is a login problem rather than a picker problem. The menu prints the machine’s own reason and a Fix this in Machines & accounts button that opens that machine’s page in Settings with its sign ins already showing.
Permission modeThe mode chip. How much the agent may do without asking. See Approvals and permissions.
Thinking levelIn the model chip. The reasoning effort dial, on models that have one. Lower levels favor speed and lower token use; higher levels spend more time and tokens on depth and checking. The menu explains each level, and the open chat's options card explains the selected one. Models without a dial say so rather than inheriting stale choices from another model.
Show thinkingClaude only. Whether the agent's reasoning is recorded into each turn, one click down from it. See Showing the agent's reasoning.
AttachThe + menu offers Attach files, slash commands, file mentions, and prompt history. You can also paste a screenshot straight into the box.
DictateThe microphone. Voice input using the browser's own speech recognition. Nothing is uploaded for transcription.
Send and StopThe white round button. An arrow sends; while a turn is running and the box is empty it shows a square, which is Stop. Send dims while the box is empty and while an approval is waiting on you, so Allow is the one bright button; Stop stays lit.
Steer or QueueAppears beside Send when you type during a running turn. Its label says what will happen: Steer delivers the message into the running turn, Queue holds it for the next one.

Above the message box sits the tray, one row for each thing the chat has to tell you: what it is doing right now (a dot and a word, such as Responding, Awaiting approval or Waiting for your answer), the agent's to-do list, a message waiting in the queue, a lock notice with its Take over button, a suggested next prompt, and your attachments. A row only appears when it has something to say, and the tray disappears when none do. The to-do row shows the completed task count and the step the agent is on now; click it to see the whole list, and click again to fold it. When every task is done it folds to its heading, which you can reopen. A task that reopens opens the list again, unless you have already chosen to fold or open it during this turn. An idle chat shows no status row. On a phone, with the keyboard up, the tray shows only its first row.

Drafts persist per chat, so switching away and back does not lose what you were typing, and neither does a reload.

The message box grows as you type, up to eight lines, and then scrolls. The controls keep their size as the box grows.

Slash commands

Typing / opens a command palette. Each row shows what the command does, what arguments it takes, and a badge when it comes from this project or a plugin rather than from your own machine. The descriptions are read off disk, so your own commands and skills are described the same way the built ins are, and searching matches descriptions as well as names, which helps when you remember what a skill does but not what it is called. Keep typing past the command name and the row stays up as a reminder of its arguments.

The list covers built ins such as /compact, /clear, /context and /model, whatever your engine's CLI advertises, and any commands or skills defined for this project. Codex is the exception in one way: it has no slash commands of its own, so picking one there sends the text to the model rather than running a command outright. Only /compact sent on its own runs as a command there: it compacts the chat, the same as the Compact button.

Starting a message with # is handled by Termdeck rather than the engine: it appends that line to the project instruction file. See MCP and project context.

Prompt history

The up arrow walks back through what you have sent in this chat. For anything else, Ctrl R with the composer focused turns the box itself into a search over your prompts: type, see every prompt that matches, take one. Esc restores what you had.

The search covers the whole project: this chat first, then every other chat in the same folder, whichever engine ran it, plus what you typed into Claude Code in a terminal there. Prompts from other chats join the list a moment after it opens and are marked other chat. Words can come in any order and a word can have letters missing, so refctr login still finds a prompt about refactoring the login page. It reaches back through your 30 most recent chats in the folder, reading the start and the latest part of each, so a prompt from the middle of a very long chat can be missing. Agents that have not updated yet search this chat only.

Files & agents (the dock)

Switch between files without losing your reading position. The dock remembers each file and its Diff, File, or source view while this tab stays open, separately for each chat and checkout. Reopening a folder checks its current contents while keeping its last listing visible.

The right hand dock, named Files & agents in the app, holds the project file browser and the diff view. The button at the right hand end of the chat title bar opens and closes it, and the same entry sits in the chat's More actions menu. Ctrl Shift F opens it, or moves focus to its file tree when it is already open. To search inside a file, use the browser's own find. It shows both the tree of the project folder and the set of files this chat has changed. Full detail is on Reviewing changes.

A filled row marks the selected file; the new, edited, and deleted labels and their colours identify Git changes. Keyboard focus has a mint outline.

The dock has three tabs. Files is the one above. Sub agents lists the agents this chat delegated to and opens each with its own transcript. Shells lists what this chat has left running. Both of the last two carry a count only when there is something to count.

Claude and Codex sub agents appear under the chat that spawned them, including when you reopen an older chat. Codex rows refresh while the dock is open and show the worker's recorded running, completed, or interrupted state. If the available records do not establish a state, the row says so. Opening a Codex row shows its own transcript without inherited parent history when Codex records that boundary. Codex workers remain view only; send follow-up instructions through their parent chat.

The Files tab is the change bar, saying how many files changed and how many lines were added and removed, and the tree of the project folder under it. A file you open appears under the tree, and its × closes it and gives the tree the whole height back. To start the dock on the tree or the viewer alone, set Pane layout in Settings, then Appearance.

With a file open, drag the divider between the tree and the file to give one of them more room. On a phone it is a grab handle you can drag with a finger; with a mouse or a keyboard it is the thin strip between the panes, and the arrow keys move it once it has focus. Double click or double tap it to hand the split back to its starting proportion.

On a phone the dock opens as a full screen sheet over the chat. The same button opens it, in the top right corner of the chat header, opposite the menu button that opens the sessions drawer on the left, Esc or the phone's Back button closes it, and while it is open the chat behind it is out of reach until you close it. The sessions drawer works the same way: Back or Esc closes it, and choosing a chat closes it for you.

Background shells

A background shell is a command the agent started and left running: a dev server, a watcher, a tail -f. A long build or test run that outran its time limit becomes one too, because Claude moves it to the background rather than stopping it. It outlives the turn that started it, which is the point of it and also the reason it needs somewhere to be seen. That includes one a sub-agent started for its own work: the chat keeps it running and the sub-agent reports on it when it finishes. This is Claude only. Codex and Grok do not report background commands, so on their chats the tab stays empty.

While a chat has sub-agents or background shells running, the tray above its message box lists each one on a single line under the status, with its task or command and how long it has been running. Click a sub-agent to open its card and transcript, or a shell to read its log. Each leaves the line when it finishes; the dock keeps the full list.

The dock's Shells tab lists them for the open chat, the sidebar marks any chat with one running, and a chat open in a Terminals pane lists its running shells above the prompt. Open a shell to read its log, tailed live while it runs, or open the command's row in the chat to follow its output in place. The browser keeps the last 256 KB of it as scrollback; the whole file stays on the machine.

A shell's Stop ends the command and everything it started, and the row reads stopped only once the machine confirms the process is gone. The stop goes through Claude itself, so the agent is told you stopped the command rather than seeing it die and reporting a failure. A command that ignores the polite signal is force killed. If it still survives, the row stays running and says so.

Stop all stops every running shell the same way, including one started moments ago whose process is not yet identified. A shell Claude does not stop is ended by closing the idle Claude process it runs under, and if Claude is replying in that chat at the time, the reply stops too and is recorded as stopped. A shell started in the reply that is still running is stopped on its own, and the reply carries on. As with Stop, a row reads stopped only once the machine confirms it; one that cannot be reached stays running.

The list is rebuilt from the chat's own transcript rather than held in memory, so it survives a reload and a Termdeck release. A shell that ended while nobody was watching reports how it ended rather than saying it stopped being tracked. If the Claude process holding a shell goes away, for example when the machine's agent restarts, the shell goes with it and its row reads ended with its turn within a few seconds. Its log can be read only while the machine still has the output file, which Claude keeps in a temporary folder; once that is cleared, the log says so. While any chat on a machine has a background shell running, an agent update waits rather than restarting the agent under it, because the restart would end the shell. It installs once the last shell ends, so a dev server left running all day keeps that machine on its current agent version until you stop it.

A shell someone ended on purpose reads stopped, in grey: stopped when you stopped it, stopped by the agent when the agent did, including when it killed the process with a command of its own. Failed, in red, is kept for a command that exited with an error by itself.

When a background command finishes, the chat picks it up by itself. You do not have to type anything. The agent is told the command ended, reads its output and carries on from where it left off, and the chat goes from idle back to running on its own. If the next thing it wants to do needs your approval, that approval arrives the way any other does: in the chat, in Approvals, and on your phone if you have push turned on. So a build you kick off before closing the tab can be finished and already acted on by the time you come back. If the machine's connection drops for a moment while that reply is running, the reply keeps going on the machine and the chat picks it back up when the machine reconnects, rather than reporting it as failed.

You can also keep talking to the chat while the command runs. Ask it for a status, send it somewhere else, change the model: the reply comes from the same agent that started the shell, so it can read the running command's output and tell you what it is actually doing. Changing the reasoning effort or the per turn spend limit is the exception. Those are fixed when a turn starts and cannot be changed under a running command, so that message begins a fresh turn instead. Your background commands keep running either way.

The other pages

Approvals

One inbox for every waiting permission across every chat and machine. Triage from the keyboard and answer in bulk when a run keeps asking the same kind of question.

Terminals

Several chats side by side, laid out like tmux with Claude Code running in each pane. Start new chats or bring running ones in, all with the mouse. See Terminals below.

Terminals

Terminals shows several chats at once, tiled edge to edge the way tmux lays out a session. The bar across the top names the page and lists your windows by name, and at its right end are ⊞ (even out the panes), ⚙ (terminal settings) and + (a new chat in a new pane). The bell, your usage and the way back to Home stay in the sidebar. Each pane opens on a card naming the agent, model and folder. Your messages sit on a band behind ❯, replies and tool calls get a ● bullet, and a tool's result hangs under it after ⎿. Every agent reads the same here: Claude, Codex and Grok chats use the same rows, folded lines and approval prompts, and a sub agent is one Task row that is also listed above the prompt while it works. While a command runs, its newest output shows above the spinner and the spinner's clock keeps counting. Live command output and streaming replies show at most three visible lines, even in narrow panes. Click Show more to scroll through the available live text, then Show less to return to the latest three lines. A new command starts collapsed. Everything under the pane's header is in the terminal font, which Font in the terminal settings picks. Each pane's header shows its number, the chat's title, its project as you named it in Settings, and the machine. Codex and Grok chats use the same layout. A Codex chat scrolls back turn by turn, and an older turn shows Show every step for its commands and edits. An approval in a Codex pane offers the choices Codex gave; one that needs a form says to open the chat with ↗. Nothing on this page needs a shortcut; every action is a click.

Adding chats

  • A running or recent chat: choose ⇄ Attach a chat on a pane, or Attach a running chat in an empty pane. The list puts chats that are working right now first. Type to search, then press Enter to open the top match, or use the arrow keys to move down the list. Pick where the chat opens: in this pane, split right, split down, or in a new window.
  • From the sidebar: click a chat to add it, or drag it onto a pane. Drop it near an edge to split that pane on that side, or in the middle to replace what the pane shows. Chats already in a pane carry a check mark in the sidebar, and clicking one takes you to its pane.
  • A new chat: click + at the right end of the bar, or + on any pane. The new pane opens on a compact card with machine, folder, agent, model and effort controls. Click a setting to change it. Agent and model menus show their logos beside each choice, with a check beside the current selection. The controls rearrange into a list in narrow panes; point at a shortened value to see it in full. Type your first message and press Enter or click ↵. The pane becomes that chat and it appears in the sidebar.
  • A fresh start in the same place: type /clear in a chat pane and press Enter. The pane turns into a new chat with the same machine, folder, agent, model, effort and permission mode already picked; change any of them before your first message. The old chat is stopped if it was working and archived, so it leaves the sidebar; unarchive it to bring it back.

Working in a pane

Click anywhere in a pane to type into it; the cursor jumps to the prompt at the bottom, so you never have to aim for it. Dragging to select text still selects it for copying. Type and press Enter or click ↵. A message sent while a Claude or Codex chat is working goes into the running turn, as it does in the chat's own message box: Claude breaks off to answer it, Codex picks it up and keeps going. It shows dimmed under the spinner until the agent takes it up, and if you stop the turn first it goes back into the prompt. On Grok, or while Claude has sub agents running, the message is queued instead and sent when the turn ends; it shows dimmed under the spinner with discard to drop it before it runs. While a turn runs, the spinner line shows how long it has been going. Under the spinner, each sub agent the chat has working gets a line: its type and task, then the tool it is using, how long it has been running, its tool calls and its tokens. They stay listed until the turn ends, and a sub agent still working in the background stays until it finishes. Next come the chat's running background shells under Shells, each with its command and how long it has been running. They stay listed after the turn ends, until the command stops. Click stop on one to end it without touching the chat, or click Shells to fold the list to one line. To read a shell's log, open the chat and use its Shells tab. Below them is the chat's to-do list, with how many items are done; the current item is in bold and finished ones are struck through. Click To-dos to fold the list to one line showing the current item, and again to open it. The list goes away once every item is done, or when you send a new message and the agent stops updating it. To interrupt it, click ■ beside ↵, click stop on the spinner line, or press Ctrl C in the pane. With text selected, Ctrl C copies it instead. Send a message to carry on from where it stopped. A pane opens on the chat's latest few messages. Scroll up to load older ones, a page at a time, back to the start of the chat; in a pane too short to scroll, scroll up anyway or click the earlier messages line. Click a tool's +N lines to read its whole output, and Thinking to open the reasoning. Files the agent reads, searches it runs and shell commands fold to one line such as Read 1 file, ran 2 shell commands; click it to see each call and its output. Edits always show in full. To see every call in full, set Reads and commands to Full in the pane settings. Pictures show in the pane: images you attached, images a tool returned, and any picture in the chat's folder the agent names by its path, such as a screenshot it just saved. Click one to see it full size. Video and audio files are not previewed. Web addresses starting with http:// or https:// are underlined links, in replies, in your prompts and in tool output; click one to open the site in a new tab. Under the prompt, the first line says where the chat runs: ◆ the project, ⎇ the git branch, ⌥ the worktree when the chat runs in one, and ⌂ the machine. The second line says what it is using: the model, after the logo of its agent (Claude, Codex or Grok), the effort, how full the context is, an estimate of what the chat has cost at API list prices, its sub agents included, each at its own model's price (≈; on a subscription you are not billed per token), and the tokens in and out. Hover any of them for what it means. The line below that starts with the chat's state: idle, working, or needs you, then how many approvals are waiting (click it to jump to the prompt) and view-only when another program is writing to the chat. When an idle Claude or Codex chat's prompt cache has expired, the line also says cache expired, next message costs more; a fresh chat is usually cheaper, as it is in the chat's own message box. Click the mode on that line, such as accept edits on, to choose the permission mode. When a chat asks for approval, a question or a plan, its choices appear in the pane as numbered buttons; click one to answer, or type its number in the prompt and press Enter. Choices that let you tell the agent what to do instead open a text box with a Send button; press Enter or click Send. For questions, choose a numbered answer or Other to type your own. A filled circle marks a single choice; checked boxes mark multiple choices. The counter shows how many questions you have answered. Review your selections, then click Submit answer or Submit answers to send them together. Use the arrow keys to move between options and Space to select. Skip, don't answer declines the request. A window with one waiting gets a dot after its name until you answer, even when it is the window you are in. A chat that finishes or fails a turn while you are on another pane, another window, another page or away from the browser gets the same dot until you click its pane or switch to it. A chat that another program is writing to is view only here too.

Arranging panes

Pane controls stay visible so you can switch tasks without hunting for them. Use Tab to reach the controls with the keyboard. When you have more windows than fit in the bar, scroll the window tabs sideways; switching windows brings the selected tab into view.

  • Use the buttons on the right of each pane header: + new chat, ⇄ attach a chat, ◫ split right, ⊟ split down, ⤢ zoom, ↗ open as a full chat, and × close.
  • Drag the line between two panes to resize them. Double click it to make them even again. ⊞ on the bar evens out every pane in the window.
  • Drag a pane by its title onto another pane to move it there; drop it in the middle to swap the two.
  • Zoom fills the window with one pane. Zoom again, or double click the title, to put it back.

Windows

Each tab in the bar is a window with its own panes, named after the agent in its active pane, such as claude, or empty when that pane has no chat yet, until you rename it. A second window with the same name gets a number, such as claude 2. Click a tab to switch, double click it to rename it, click the × beside it to close it (a window with chats in it asks first; the chats keep running and stay in the sidebar), and click + after the tabs to open a new one. The window you are looking at is filled. A dot after a window's name means a chat in it is waiting for an approval, a question or a plan, or finished a turn you have not looked at yet. Hover the tab to see which. Your windows and panes are remembered in this browser.

On Starter a window holds up to 4 panes, a 2x2 grid. Adding a fifth to a full window opens an upgrade prompt; you can still replace what a pane shows or open another window. Pro holds up to 9 in a window.

Notifications in Terminals

The bell stays at the foot of the sidebar here, with the same count. Popups still drop in at the top right, but they lead to panes: Go to pane switches to the window holding that chat and highlights its pane, or opens the chat in a new pane. A request for a pane already on screen shows in that pane only, with no popup, and a turn that finishes in the pane you are in brings no popup either. See In app alerts.

Customizing

Click ⚙ on the bar. Every change shows at once and is kept in this browser:

  • Theme: the panes' colours: Termdeck (the default), Claude dark, Claude light, tmux classic, Solarized, or Dracula.
  • Text: Font, the font for everything in a pane under its header, and the text size, from 12 to 24 pixels. It starts at 16.
  • Panes: border style, and whether each pane shows its title line. With titles off, the title and its buttons appear when you hover the pane.
  • Transcript: how many lines of tool output show before +N lines, whether thinking is folded, open or hidden, the welcome banner, timestamps, and the status lines under the prompt.

Reset to defaults puts all of it back. Each pane keeps your place: switch windows, leave the page or reload, and a pane you had scrolled up in is still on the same line. Only the panes in the window you are looking at are live. Panes in other windows load nothing and stay quiet until you switch to that window, then catch up at once; their tabs still show the dot while you are away. Leave the page and every pane pauses, and coming back catches the window you are on up. When a machine reconnects, its panes keep what they show and catch up the same way. A pane that cannot load its chat says why; click the message to try again. Terminals needs a wide screen: on a phone the page says so and offers the way back to Home.

Status notices appear at the bottom right; chat notifications appear at the top right. Each corner keeps up to four cards. Hover over a timed card or focus a control inside it to pause its dismissal. Use the close button to dismiss it, or swipe it sideways on a phone. Connection notices change to Back online when the browser reconnects.

Settings

Settings opens inside the app, beside the sidebar, where the chat or page you were on was. Open it with the gear at the foot of the sidebar, or by clicking your name there. Use the sidebar to go anywhere else; nothing reloads on the way in or out. On a desktop, the grouped list of sections stays beside the section you are editing, and Settings opens on General. On a phone, Settings opens on the grouped list; choosing a section opens it, and ‹ Settings at its top goes back to the list.

GroupSectionHolds
PreferencesGeneralThe default permission mode and the account-wide reasoning switch, machine-specific defaults for new chats (engine, model, thinking level), and the per turn spend cap. Existing chats keep their own.
AppearanceHow the files dock opens and which panes it shows, line wrapping, and whether the sidebar shows its Usage line. Tool colors opens its own page, where you recolour any tool in the transcript, add one by name, or reset them.
NotificationsPush on this browser, and for each event (approvals, questions and plans, finished turns, failed runs) whether it reaches you by push, in-app popup, sound, or not at all.
ChatsAuto archive after an idle period, plus what the chat list shows and hides.
Keyboard shortcutsEvery keyboard shortcut, grouped by composer, chat and app, with the keys for your computer (Cmd on a Mac).
WorkspaceMachines & accountsA list of your machines. Click one for its own page: the CLIs on it, their sign ins, health, configuration and maintenance.
ProjectsWhich folders appear in the sidebar and board, per machine.
ExtensionsMCP servers, plugins and skills on each machine.
ApprovalsFour cards: tools that always run, your saved rules, suggested rules, and the guards that always refuse.
AccountProfileYour name, plan, and a year of the turns you ran through Termdeck. Edit changes your name.
AccountYour name (the pencil changes it), username, email and how you sign in, plus Report a bug and Log out.
Security & loginChange or set your password, see every browser signed in to your account and log any of them out.
UsageOverview: your plan's limits and each coding CLI's rate limits. Analytics: tokens and cost by project, model, and day. See Usage and cost.
BillingYour plan and its status, changing or cancelling it, promo codes, and your payment history.
DataArchived chatsChats you or the idle rule archived, grouped by project, with search, filters, Open and Unarchive. See Archived chats.
Data controlsRestore layout defaults without erasing preferences, or clear all of this browser's Termdeck data.

Every section is deep linkable, for example /settings/approvals, so a bookmark or support link opens that section inside the app. Switches and menus save automatically, with no confirmation to wait for. If a change cannot be saved, a notice says so at the bottom right and the control goes back to the value that is really stored, so you can try again. Text you type (a name, a rule) is saved from the dialog it opens in, when you press its save button.

To find a setting without knowing its section, type in Search at the top of the section list; on a desktop it is ready to type into as soon as Settings opens. The results replace the list and show which section each setting lives in, and common synonyms work too: budget finds the spend cap and sign out finds Log out. Use the arrow keys to move through them and Enter to open one, or click it: its section opens with that setting scrolled into view and ready to change. Press Escape or × to go back to browsing.

Escape steps back one thing at a time: it closes an open menu first, then clears the search, then leaves a page inside a section, such as one machine on Machines, and stops there.

Keyboard shortcuts

The same list is in Settings, under Keyboard shortcuts, where it shows the keys for the computer you are on. On a Mac, press Cmd where a row says Ctrl, except Ctrl B and Ctrl C, which stay on the Control key. The Approvals page keys work only while you are not typing in a box.

KeysAction
EnterSend the message
Shift EnterStart a new line
↑Recall what you sent before, with the cursor at the start of the box
Ctrl RSearch prompt history, with the composer focused
Ctrl Shift FOpen the project file explorer in the dock
Ctrl CStop the running turn in the focused Terminals pane, when no text is selected
Ctrl KOpen the command palette
Ctrl BCollapse the sidebar, or open the drawer on a phone
Alt 1-9Jump to a pinned chat, or go to that pane on the Terminals page
EscClose the open menu, sheet, or dialog
J or ↓On the Approvals page, move to the next request
K or ↑On the Approvals page, move to the previous request
EnterOn the Approvals page, expand or collapse the request
OOn the Approvals page, open the chat that asked
AOn the Approvals page, allow the request
DOn the Approvals page, deny the request
Shift AOn the Approvals page, allow every low-risk request

Layout is per browser, not per account, so the sidebar width you like on the desktop does not follow you onto the phone. Settings, then Data controls restores layout defaults without changing preferences.