@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 03:37 UTC

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