1# Working with threads
2
3Use a new thread for a separate task. Choose **New worktree** when its code changes
4need a separate branch and working directory.
5
6## Start a thread
7
8On web and desktop, **New thread** opens the project picker when you have more than one
9open project in the default or project-grouped sidebar. Archived projects don't count. **Shift-click** to start in
10the current project, or use a project's own new-thread action. A new thread carries
11your model and mode selections, unless the destination project has its own model default.
12Its branch and workspace mode come from your configured defaults. To continue in
13an existing worktree, use **New thread in this worktree** from the branch toolbar.
14
15On mobile, **New thread** starts in the current thread's project, or else in the
16last project you opened or chose on that device. If neither is available, the
17project picker opens. Turn off **Settings → General → Use last project** to
18choose a project every time. When you pick a project that is on more than one
19machine, the thread starts on a connected one if any is connected.
20
21When you change a new thread's project, T3 Code stays in the current environment
22if that project exists there. Otherwise it selects an environment that has it.
23
24### Start without a project
25
26A thread does not need a project. To start one without a project, click **or
27start without a project** under a new thread's heading, pick **No project** from
28the project menu in that heading or from **New thread in...** in the command
29palette, or press `mod+alt+n`. On mobile, pick **No project** from the project
30list. It starts on your current machine; before sending, pick another machine
31from the machine menu to move it there. To move a draft into a project, pick the
32project in the heading.
33
34Each thread without a project works in its own folder under `~/.t3/scratch` (the
35`scratch` folder of your T3 data directory), named after its date, the first words
36of its first message, and a short id, like
37`2026-09-25-convert-these-pngs-to-webp-a1b2c3d4`. Deleting a thread keeps its
38folder, so the files the agent wrote stay until you delete them. Branch, worktree, and diff controls stay hidden because
39these folders are not Git repositories. This is unavailable when the data
40directory itself sits inside a Git checkout.
41
42When the work grows into something real, pick **Turn into project** from the
43thread's menu. The thread's folder becomes a project where it is, so nothing
44moves and the agent keeps working in the same place. Other threads in that folder
45move with it. Rename the project in its settings, and use **Initialize Git** to
46get branch and diff controls.
47
48### Start in the background
49
50In a desktop browser or the desktop app, press `Cmd+Enter` on macOS or `Ctrl+Enter`
51on Windows and Linux to start a new thread and immediately open another draft. The
52next draft keeps the workspace mode and base branch you selected. With **New
53worktree**, each background submission creates its own worktree.
54
55To send the same prompt to several models on web or desktop, **Shift-click** models
56in a new thread's model picker to add or remove them. A regular click returns to a
57single model. Choose a base branch and send. Each selection starts a separate thread
58and worktree while you stay in the new thread composer. This requires a Git project.
59
60## Pin and reorder threads
61
62Pin a thread from its menu to keep it above your active work.
63
64On web and desktop, unpinning, settling, snoozing, and archiving a thread each show
65a notification with **Undo** for five seconds. Undo restores the thread's previous
66state, including its pinned position, and reopens an archived thread you were
67viewing. Discarding an unsent draft from the sidebar works the same way: Undo brings
68back its text and attachments. `mod+z` triggers the most recent Undo, even from the composer; see
69[Keybindings](./keybindings.md#commands-with-special-behavior).
70
71On web and desktop, you can also drag files from your computer onto any thread row:
72the thread opens and the files are attached in its composer, ready for
73your next message. The same per-message file limits apply as when attaching
74files directly; see [Attach files](./composer.md#attach-files).
75
76On web and desktop, pinning or unpinning a thread keeps the sidebar at your current
77scroll position instead of following the thread to its new place in the list.
78
79Pinning does not prevent automatic settlement. Settling a thread removes its pin.
80
81On web and desktop, drag a thread between sections to change its state. Drag a thread up into
82the pinned section to pin it at the spot you drop it; drag a pinned thread down into the active
83list to unpin it. Dragging a thread onto the **Settled** header settles it, and dragging a settled
84thread into the active list un-settles it. A snoozed thread can be dragged out of the snoozed
85shelf, which wakes it, but threads cannot be dragged into the shelf because snoozing needs a wake
86time. Dragging a pinned thread out of the pinned section does not ask for unpin confirmation.
87Pinned and active boundary labels appear only while dragging, without moving the rows. The
88other rows slide aside to show where the thread will land. When you cross into another section,
89the dragged thread shows the action the drop performs, with its icon: **Pin**, **Unpin**,
90**Settle**, **Un-settle**, or **Wake**. Its status and hover actions hide during the drag. A pinned
91thread keeps its pin only while it stays in the pinned section; once it leaves, the badge takes
92over. Reordering within the same section shows no badge. When there are no pins, drag to the top
93edge to pin a thread. Section labels stay readable for the whole drag, and the section the
94thread is over takes the accent color. Section labels also
95identify empty sections and a collapsed settled shelf.
96
97Drag within the pinned or active section to change its order. Other rows slide aside to show the
98spot where the thread will land. Drops into either section keep the position you choose. On
99mobile, open a thread's menu and choose **Arrange threads**. Drag a handle within or between
100**Pinned** and **Active** to reorder, pin, or unpin. Drop onto the **Settled** divider to
101settle a thread. The dragged card shows the action before you release it. Expand **Snoozed**
102or **Settled** to drag a parked thread back into either live section. Each drop saves; close the sheet to return to the thread list.
103**Move up** and **Move down** are also available in the thread menu. The server
104saves the order, so it survives a refresh and appears on your other connected devices.
105
106On web and desktop, the list also animates section changes made with thread actions such as
107**Pin**, **Settle**, and **Snooze**. These transitions respect your system's reduced-motion
108preference. While dragging, rows follow the insertion gap without replaying a second transition
109after the drop.
110
111New threads appear above the active threads you have arranged. Settling clears a thread's active
112position, so using **Un-settle** returns it to the top. Pinning and snoozing preserve its active
113position until you move it again. Thread activity does not change the order. The settled shelf
114continues to use settlement time.
115
116If dragging is unavailable for one environment, update the T3 Code server running in that
117environment. Pinned and active reordering require server support. Threads from older servers keep
118their default order until the server is updated.
119
120To generate a fresh title from the conversation, open a thread's menu and choose
121**Regenerate title**. The action is unavailable while title generation is in progress
122or when the connected environment needs a server update.
123
124To change how titles are written, add **Thread title instructions** in **Settings → Threads →
125Text generation**, under Advanced, such as a length limit or an identifier to put first. They apply to new and
126regenerated titles. Select a project to give it its own instructions.
127
128Agents connected through T3 Code can use the same server-owned metadata workflow to
129rename a thread, regenerate its title, or link and unlink a pull request. These changes
130appear on web, desktop, and mobile without requiring the originating browser to remain
131open.
132
133### Fold working threads (beta)
134
135Threads that are working or waiting on work they will resume from move into a collapsed
136**Working** section below the active list.
137That includes subagents, watched pull requests, and background commands or monitors the agent
138says it is waiting on. A dev server or other process an agent leaves running does not keep a thread
139there. A thread returns to the top of the active list when it finishes, fails, or needs an approval or
140answer. The Working section lists the thread you last sent work to first. Pinned threads stay in
141the pinned section.
142
143This is on by default. Turn it off with **Settings → General → Working section** on web and desktop,
144or **Settings → General → Working section** on iOS and Android. Each device keeps its own
145choice.
146
147While this is on, the active list is ordered by when each thread last came back to you, so you
148cannot drag or move threads within it. Your saved order returns when you turn it off.
149
150### Group threads by project (beta)
151
152Turn on **Settings → Labs → Boring sidebar (group by project)** on web and desktop to put active
153threads in a folder for each project. Pinned projects come first. A project with no active
154threads has no folder unless it is pinned or you pick it in the project filter. An archived
155project's folder comes last and shows only while it has active threads. Click a folder to open or
156close it. A closed folder shows how many threads it holds, and a dot when one of them
157needs you. Use the pen button on a folder, or right-click it, to start a thread in that project.
158Pinned threads stay above the folders, and Snoozed and Settled stay below them. In this mode you
159can drag a thread onto the composer to mention it, but not within the sidebar, and the Working
160section is off. Each device keeps its own choice.
161
162## Settle finished work
163
164Choose **Settle thread** from its menu to move finished work out of the active list
165without deleting the conversation. **Un-settle thread** restores it to active work
166and prevents automatic settlement until new activity resumes the usual rules.
167Manually settling an idle thread dismisses unanswered async questions without
168sending an answer or restarting the agent. Settling also closes the thread's
169terminals that wait at an idle prompt, and keeps their output. A terminal that
170runs a command, such as a dev server, stays open unless its action has **Stop this action
171when the thread settles** enabled in Settings > Projects > Actions. You can also set
172`"stopOnSettle": true` on a `t3.json` action and import it there. Start the command through
173that action so T3 can stop its terminal and child processes. Commands started through an
174agent's own shell tools are managed by the provider.
175
176To reclaim disk space from settled work, turn on **Run in the thread's worktree when the
177thread settles** for one of the project's actions, or set `"runOnSettle": true` on a
178`t3.json` script, for example `cargo clean`. It runs each time a thread in its own
179worktree settles, manually or automatically, even if a terminal there still runs a
180command such as a dev server. Threads in the project's main checkout skip it. Its terminal
181closes when the command succeeds and stays open when it fails.
182
183On web and desktop, press a thread's **Settle** button and drag up or down to
184settle every thread in that section between it and the one you release on.
185The **Un-settle** and **Wake** buttons work the same way in their sections.
186Press `Escape` while dragging to cancel.
187
188By default, environments settle inactive threads after seven days and settle
189threads whose pull request merged. A closed pull request can also settle an idle
190thread. An empty thread's inactivity counts from when it was created.
191Work in progress, pending questions or approvals, and background work the agent
192is waiting on prevent automatic settlement. An open pull request does not prevent inactivity
193settlement unless you turn on **Keep threads with a PR** in **Settings → Threads**,
194but an old closed or merged pull request does not settle work you
195resumed after it closed. Only your own messages count as resuming. A turn that
196finished background work or a pull request watch starts on its own does not.
197
198To keep one thread out of the settled shelf no matter how long it sits idle, open its menu,
199choose **Auto-settle behavior**, and pick **Never**. The current option is checked. Pick
200**Follow settings** to return to the rules in **Settings → Threads**. While those rules are off,
201a thread on **Follow settings** does not settle automatically either. Manual settle, snooze, and
202archive still work while it is set to **Never**.
203
204Change these rules in **Settings → Threads**.
205They continue to run when your apps are closed. On web and desktop, choose an environment at the
206top to change only its rules, or **All environments** to update connected environments together.
207Mixed values show where the selected environments disagree. Mobile applies these
208rules to connected environments that support shared settings. Offline environments
209and older servers keep their previous values. Changing a rule does not reopen
210already settled threads.
211
212## Link a pull request
213
214The server finds the PR for each unsettled thread's saved branch, even when your
215apps are closed. Settled threads keep their saved links. Update the server if
216automatic branch links do not appear.
217
218On web and desktop, right-click a pull request link in a thread and choose
219**Link to thread** to select a different PR. Use **Unlink from thread** on the
220same link to return to the branch PR, if one exists.
221The linked pull request participates in automatic settlement.
222
223## Find and reference work
224
225On web and desktop, open the command palette with `Cmd/Ctrl+K` to search threads
226across connected environments by title, branch, pull request, or project.
227Threads you open often or recently rank higher, and for three weeks the thread
228you last picked for a query ranks higher when you type that query again.
229Threads whose messages contain all your words appear below, under **In
230messages**, and open at the matching message. Message search needs at least
231one word of three or more letters, or two for Chinese, Japanese, and Korean.
232On mobile, the thread list search also lists message matches and opens them at
233the matching message; on an iPad with a keyboard, `Cmd+K` opens the same
234palette.
235
236Use **Settings → Keybindings** to find or customize shortcuts for searching files
237and copying a thread reference. A copied reference uses the thread's pull request
238link when available, otherwise a link to the thread, which opens it from anywhere
239you paste it and pastes into a composer as a thread chip (see
240[sharing a thread](./prompt-links.md#share-a-thread)). To copy the thread even
241when it has a PR, choose **Copy → Thread** from its context menu, or **Copy
242thread** from its long-press menu on mobile.
243**Thread ID** copies the bare ID for scripts and the `t3` CLI. See
244[keybindings](./keybindings.md) for custom configuration.
245
246## Inspect agent work
247
248**Limited** means the provider stopped on a usage or rate limit. The conversation
249keeps the provider's explanation. Retry after the limit resets, or switch to
250another provider instance.
251Press **Resume** in an empty composer to continue a limited or interrupted turn
252manually. Do this when the provider reports no reset time, because nothing
253continues the turn on its own.
254Queued messages stay saved while the limit blocks the thread. They run after
255the continuation finishes. If the queue was held by a restart, resume it then.
256
257When the provider reports a reset time, choose **Resume at reset** to schedule a
258continuation. You can cancel it from the thread. Enable **Resume after
259usage limits** in **Settings → Threads** to schedule limit stops by default.
260The environment must be running when the reset arrives; it resumes overdue
261continuations after a restart. Stopping the thread, sending a new message,
262archiving, or settling it prevents a pending continuation from starting.
263
264Choose **Snooze until reset** to hide the thread until its allowance returns.
265Snooze and auto-resume are independent: snooze alone wakes the thread without
266sending a message; enabling both wakes and continues it. **Wake now** cancels
267the snooze. Enable **Snooze until limits reset** in thread behavior settings to
268snooze limit stops by default. Providers without a reset time offer manual
269retry and the normal snooze choices.
270
271On web and desktop, use **Agents** to follow work delegated to subagents.
272On mobile, open a subagent from its conversation card or **Agents**. On iOS
273layouts with an inspector, its thread opens beside the parent. Maximize it to
274fill the screen; close the full-screen view to return to the parent and inspector.
275Stop on a thread also stops the subagents it delegated to.
276
277Subagent threads started by the agent can't take messages; message the parent
278thread instead. When such a subagent needs an approval or an answer, the parent
279thread asks for it.
280
281Expand a tool call in the conversation to see its full command and output.
282Summaries shorten shell wrappers and can still describe the latest call after it
283finishes; the call's own result shows its status.
284
285On web and desktop, the thread details card lists the local servers that the
286thread's terminals or its Claude agent started, with their ports. Not every one
287serves a web page. A server the agent started stays listed after the agent's
288turn ends.
289Select a server to open it in the browser panel. **Stop** ends the server's job
290and keeps the agent, the terminal, and T3 Code running. Stop needs terminal
291access to the environment and is not available on Windows.
292
293To choose what the thread details card shows, right-click the card or open
294**Settings → Appearance → Thread details**. Hidden rows keep their keyboard
295shortcuts, such as Open in editor and project scripts. **Reset to default** brings
296back the standard rows.
297
298## Side chats
299
300A side chat lets you ask a question about a thread without adding to it. It starts
301with what the thread knows, and the thread keeps working while you ask.
302
303On web and desktop, start a message with `/side` or `/btw`, then your question.
304You can also choose **Side chat** from the **+** menu in the right panel. The side
305chat opens as a tab there, with its own composer. Side chats do not show in the
306sidebar. Find one again under **Side chats** in thread details.
307
308A side chat works in the same folder as the thread and starts with the permissions,
309model, and reasoning level shown in the thread's composer, including for its first
310reply. Change them for an individual side chat in its composer. Later changes to the
311parent do not change existing side chats.
312
313To use what you learned, choose **Bring back**. The thread gets the side chat with
314your next message there. Bring back is available while the thread is idle.
315
316Closing a side chat you never sent a message in deletes it. To delete one you used,
317choose **Delete** at the top of the side chat. Deleting a thread also deletes its
318side chats.
319
320On mobile, a thread lists its side chats above the composer. Tap one to open it and
321answer its questions.
322
323## Snooze until later
324
325To change the choices in the snooze menu, open **Settings → Threads → Snooze options**.
326Each option is a duration, such as 3 hours, or a time on a day, such as 9:00 PM
327tomorrow. A weekday means the next one after today. Menus list the options soonest
328first and hide a today option after its time passes. Saved with **All environments**
329selected, the options apply to every connected environment, and the mobile app uses them too.
330
331Choose **Snooze → Custom…** from a thread's menu to pick a date and time in your
332local time zone, or a duration in minutes, hours, or days. Durations start when
333you confirm; one day means 24 hours. On web and desktop, you can also snooze
334several selected threads together. Choose **Wake thread** to bring a thread back early.
335
336A snoozed thread keeps working and stays hidden until its wake time, even while
337its agent wakes itself for background work. It comes back early for an approval,
338a new question, a failed run, or a message or answer you send. You can snooze an existing
339question and answer when the thread wakes; the question stays unanswered.