Chats and sessions

Starting a chat

Choose New chat and pick three things: the machine, the folder, and the engine. The folder is the working directory the agent runs in, so it decides which repository the agent can see, which environment it inherits, and which project context files it reads.

The folder picker browses the real filesystem on the machine you selected, so you can point at a directory that has never had a chat in it. Model, thinking level, and permission mode default to what you set in Settings, then General, and can be changed per chat afterwards.

Titles and organisation

Chats title themselves from the first prompt. Rename any chat from its row menu; the new name is yours and does not get overwritten.

• Pin puts a chat in the tab strip along the top.
• Archive moves it to the Archive page. Nothing is deleted and it can come back.
• Hide takes it out of the list without archiving, for chats you want to stop seeing.

In Settings, then Chats you can auto archive anything untouched for 7, 30, or 90 days, and choose whether chats started in a terminal appear alongside the ones you started here.

Working across the browser and the terminal

Because both read and write the same session files, a chat can move between them freely.

• Start in a terminal, walk away, and the chat is already in your sidebar. Continue it in the browser.
• Start in the browser and later resume it locally with claude --resume or codex resume.
• Read a chat on your phone that is running on a machine you are not sitting at.

View only mode

The one rule this creates: two writers on one transcript would fork it, so Termdeck never allows that. If a session is attached to another process, typically a terminal running the CLI on that same chat, the composer locks and the chat becomes read only in the browser. You still see everything as it happens, and the composer unlocks by itself once the other process lets go.

If you want to send a prompt right now, you do not have to go and find the other client. The lock names what is holding the chat and offers the way out that fits it.

• Take over closes an idle terminal client. That terminal can pick the session back up later by resuming it.
• Force take over reaches any other holder, busy or idle: a desktop client, an editor chat, a scripted claude -p, another Termdeck. Termdeck asks it to exit and kills it if it does not, so a turn it was running is interrupted and anything it had not written to disk is lost.
• Take over anyway is the last resort, offered when there is no process to signal or when a force did not land. Nothing is closed. Termdeck stops enforcing the lock, which means the other client may still be writing, and two writers on one transcript is the thing that forks it. It asks you to confirm for that reason.

Codex and Grok keep no process registry, so a chat of theirs that another client touched recently offers the last option directly, or unlocks by itself once it goes quiet. One lock has no way out by design: a Codex sub agent working for another chat refuses input, so reply in the chat that spawned it.

Starting a fresh chat in the same folder is still the calmest option when the other session is somebody else's work.

While a turn is running

The composer's send button becomes Stop. Stopping asks the engine to end the turn cleanly; what it has already written to disk stays written.

Closing the tab does not stop the run. Neither does losing your connection, putting the laptop to sleep, or a Termdeck release. The agent keeps the process alive across a dead link and replays what you missed when you come back. A run only ends when it finishes, when you stop it, or when nobody reconnects for several minutes.

Queueing follow up turns Starter

Send while a turn is running and the message is queued rather than rejected. Queued turns run in order as the current one finishes, so you can line up three follow ups and leave. The queue survives a server restart and holds up to 20 messages per chat.

On engines that support steering, a queued message can be delivered into the running turn instead of waiting for the next one. Where that is not available it falls back to queueing, so the behaviour is never a surprise.

Per turn spend ceiling

A turn can be given a maximum spend. The engine enforces it itself and ends the turn when the ceiling is reached, which is the only way a ceiling is actually a ceiling. Checking between operations always overshoots.

This is a safety rail you set for yourself against a runaway agent, not a plan limit. The tokens are yours, billed to Anthropic, OpenAI, or xAI under your own subscription, and Termdeck has no interest in rationing them. Machine operators can also set a hard ceiling with TERMDECK_MAX_BUDGET_USD, and the smaller of the two always wins.

Images and files

Attach images and files from the composer, or paste a screenshot straight into it. This is the fastest way to hand an agent a failing UI, a stack trace screenshot, or a design.

Managing the context window

The strip above the composer shows how much of the model's context window this chat is using, measured against the window the CLI itself reports rather than a hardcoded number. When it gets full, Compact asks the engine to summarise the conversation so far and continue with the shorter version, which is the same thing /compact does.

Compacting is lossy by design. If a chat has drifted far from what you actually want, starting a fresh chat in the same folder is often better than compacting a long one.

Showing the agent's reasoning

Claude can write a summary of how it reasoned into each turn, one click down from the reply. The thinking control in the message box sets it for the open chat, Shown or Hidden. Hidden is not a display filter: the engine stops producing the text at all, so a turn that runs while it is off has no reasoning to go back for afterwards.

Settings, then General holds the default every Claude chat follows until it says otherwise. It is stored on your account rather than in the browser, so it reads the same on your laptop and your phone, and the thinking control badges whichever answer the account is on. A chat that has chosen for itself keeps its own answer.

Both take effect from the next turn. A turn already running keeps the setting it started with, whichever way you move the control while it runs, and turns already on disk keep what they recorded. That is the engine's behaviour rather than a Termdeck limit, measured against the CLI in both directions.

Codex and Grok have no equivalent control, so their chats show none.

Recap

Recap, in a chat's own menu, produces a factual summary of what it did: how long it ran, how many turns, which files it touched, what commands it ran, and what it cost. It is derived from the transcript rather than generated by a model, so it costs nothing, is instant, and cannot be wrong about which files were edited. It deliberately does not attempt to say why, since that is the part a summary would have to invent.

Copying replies, code and output

Hover any reply, tool call, thought, or fenced code block and a copy button appears in its corner. An assistant reply's button takes the whole message; a fenced code block inside one has its own, so you don't have to pick it back out of the prose. Open a tool call and its command and its result each get a copy button too, for taking a path, an error, or a build's output somewhere else. Open a thought and it reads like a reply, not like a command's output, with the same copy button on hover.

Finding an old chat

The board filter matches prompt text, project, and machine at once, and works across the whole fleet on Pro. The Archive page holds everything you or the idle rule put away. Chats are never deleted by Termdeck: the records belong to the CLI and live on your disk.

What counts as a turn

On Free, browser started turns are metered, currently 30 a month. A turn is one prompt you send from Termdeck. Reading transcripts, approving or denying tool calls, stopping a run, and turns you start in a terminal are all unmetered and always will be, on every plan. The purpose of the free tier is that you can always unblock an agent that is waiting on you.