termdeck
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.
The sidebar
The sidebar is the primary navigation at every screen size. On a phone it becomes a drawer rather than disappearing.
The top rail holds the pages: Home, Approvals, Terminals, Usage, Archive, and New chat. Below it is the chat list, grouped by project folder. At the bottom sits the live rate limit panel and your account.
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. Chats running in a git worktree are folded into the base repository rather than showing up as a separate project you never added.
Ctrl B collapses the sidebar on desktop and opens the drawer on a phone. Drag the right edge to resize it, or double click that edge to reset.
Reading a chat row
Each row carries a status badge derived from what the transcript and the live stream say: running, needs you, reading, done, or failed. The same derivation drives the board, the tab title count, and the notification list, so those three can never disagree with each other.
Right click a row for its actions: pin, rename, archive, hide, copy the session id, or open the folder it runs in.
The fleet board
Clicking Home with no chat open lands on the board. It is one card per chat, grouped by run state rather than by project, across every machine and every engine. This is the view for the question "what is happening right now", when the answer spans a laptop, a desktop, and a build VM.
The filter box at the top matches on prompt text, project, and machine at once. Select mode lets you act on several chats together, which is the fastest way to archive a week of finished work.
Pinned tabs
The strip along the top holds pinned chats. Pinning is how a chat stays one click away while you work through several at once. Alt 1 to Alt 9 jump straight to the first nine, and a draft you were typing survives the jump.
The transcript
The transcript is the chat itself, rendered from the engine's own records with the live stream layered on top.
- Tool calls fold up into one line each with a summary of what they did, and open on click.
- 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 show as a status strip beside the composer: what is running, what finished, and what it is currently doing. The dock's Sub agents tab opens one, with what it was asked to do on the left and its own transcript on the right.
- 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.
Above the composer sits the context strip: how much of the model's window the conversation is using, and a Compact button when it is getting full.
The composer
The composer is where you send prompts and where every per chat control lives.
| Control | What it does |
|---|---|
| Model | Picks the model for this chat, from the catalog the CLI itself reports. An empty list means the CLI could not answer, which is a login problem rather than a picker problem. |
| Permission mode | How much the agent may do without asking. See Approvals and permissions. |
| Thinking level | The reasoning effort dial, on models that have one. Models without one show no dial rather than a fake one. |
| Show thinking | Claude only. Whether the agent's reasoning is recorded into each turn, one click down from it. See Showing the agent's reasoning. |
| Attach | Images and files. Paste a screenshot straight into the box. |
| Dictate | Voice input using the browser's own speech recognition. Nothing is uploaded for transcription. |
| Send and Stop | Send starts a turn; while one is running the same place holds Stop. |
Drafts persist per chat, so switching away and back does not lose what you were typing, and neither does a reload.
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.
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 older, Ctrl R with the composer focused turns the box itself into a search over your prompt history: type, see every prompt containing it, take one. Esc restores what you had.
The dock
The right hand dock holds the project file browser and the diff view. Ctrl Shift F opens it, Ctrl F searches inside the open file. It shows both the tree of the project folder and the set of files this chat has changed. Full detail is on Reviewing changes.
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, and a live dot while something is still going.
Background shells
A background shell is a command the agent started and left running: a dev server, a watcher, a tail -f. It outlives the turn that started it, which is the point of it and also the reason it needs somewhere to be seen. This is Claude only. Codex and Grok do not report background commands, so on their chats the tab stays empty.
The dock's Shells tab lists them for the open chat, and the sidebar marks any chat with one running. Open a shell to read its log, tailed live while it runs. The browser keeps the last 256 KB of it as scrollback; the whole file stays on the machine.
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.
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
Every chat as a live pane on one canvas, in a grid, across machines and engines. Alt and a digit raises a window while you are on this page.
Usage
Tokens and cost by project, model, and day, over a range you choose. See Usage and cost.
Archive
Chats you have archived, or that the idle rule archived for you. Nothing is deleted, and anything here can come back.
Settings
Settings is its own page, and its sections sit in two groups. Personal holds Account, General, Appearance, Notifications, Chats, and Data and reset. Workspace holds Projects, Approvals, and Machines and accounts. Usage and billing and your archived chats are links out of the same rail.
| Section | Holds |
|---|---|
| Account | Your profile, subscription, and any creator code you want to redeem. |
| General | Defaults for new chats: engine, model, thinking level, permission mode. Existing chats keep their own. Also the one account-wide switch, for showing the agent's reasoning. |
| Appearance | Theme, the sidebar footer, and the colour each tool gets in the transcript. |
| Notifications | Push subscription and which events are worth a notification. |
| Chats | Auto archive after an idle period, plus what the chat list shows and hides. |
| Data and reset | Undo layout changes and clear this browser's local data. |
| Projects | Which folders appear in the sidebar and board, per machine. |
| Approvals | Auto allow rules and the hard deny switches. |
| Machines and accounts | Your machines, the CLIs on them, their sign ins, and the diagnostics. |
Every section is deep linkable, for example #/settings/approvals, so a bookmark or a support link lands on the right panel.
Keyboard shortcuts
| Keys | Action |
|---|---|
| Ctrl B | Collapse the sidebar, or open the drawer on a phone |
| Ctrl Shift F | Open the project file explorer in the dock |
| Ctrl F | Find inside the file open in the dock |
| Ctrl R | Search prompt history, with the composer focused |
| Alt 1 to Alt 9 | Jump to a pinned tab, or raise a window on the Terminals page |
| Esc | Close the open menu, sheet, or dialog |
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 and reset puts any of it back.