clover's git

the-knife

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, a new thread keeps the current project and carries your model
9	and mode selections, unless the destination project has its own model default.
10	Its branch and workspace mode come from your configured defaults. To continue in
11	an existing worktree, use **New thread in this worktree** from the branch toolbar.
12
13	When you change a new thread's project, T3 Code stays in the current environment
14	if that project exists there. Otherwise it selects an environment that has it.
15
16	### Start without a project
17
18	A thread does not need a project. To start one without a project, click **or
19	start without a project** under a new thread's heading, pick **No project** from
20	the project menu in that heading or from **New thread in...** in the command
21	palette, or press `mod+alt+n`. On mobile, pick **No project** from the project
22	list. It starts on your current machine; before sending, pick another machine
23	from the machine menu to move it there. To move a draft into a project, pick the
24	project in the heading.
25
26	Each thread without a project works in its own folder under `~/.t3/scratch` (the
27	`scratch` folder of your T3 data directory), named after its date, the first words
28	of its first message, and a short id, like
29	`2026-09-25-convert-these-pngs-to-webp-a1b2c3d4`. Deleting a thread keeps its
30	folder, so the files the agent wrote stay until you delete them. Branch, worktree, and diff controls stay hidden because
31	these folders are not Git repositories. This is unavailable when the data
32	directory itself sits inside a Git checkout.
33
34	### Start in the background
35
36	In a desktop browser or the desktop app, press `Cmd+Enter` on macOS or `Ctrl+Enter`
37	on Windows and Linux to start a new thread and immediately open another draft. The
38	next draft keeps the workspace mode and base branch you selected. With **New
39	worktree**, each background submission creates its own worktree.
40
41	To send the same prompt to several models on web or desktop, **Shift-click** models
42	in a new thread's model picker to add or remove them. A regular click returns to a
43	single model. Choose a base branch and send. Each selection starts a separate thread
44	and worktree while you stay in the new thread composer. This requires a Git project.
45
46	## Pin and reorder threads
47
48	Pin a thread from its menu to keep it above your active work.
49
50	On web and desktop, unpinning, settling, snoozing, and archiving a thread each show
51	a notification with **Undo** for five seconds. Undo restores the thread's previous
52	state, including its pinned position, and reopens an archived thread you were
53	viewing. Discarding an unsent draft from the sidebar works the same way: Undo brings
54	back its text and attachments. `mod+z` triggers the most recent Undo when no text field is focused; see
55	[Keybindings](./keybindings.md#commands-with-special-behavior).
56
57	On web and desktop, you can also drag files from your computer onto any thread row:
58	the thread opens and the files are attached in its composer, ready for
59	your next message. The same per-message file limits apply as when attaching
60	files directly; see [Attach files](./composer.md#attach-files).
61
62	On web and desktop, pinning or unpinning a thread keeps the sidebar at your current
63	scroll position instead of following the thread to its new place in the list.
64
65	Pinning does not prevent automatic settlement. Settling a thread removes its pin.
66
67	On web and desktop, drag a thread between sections to change its state. Drag a thread up into
68	the pinned section to pin it at the spot you drop it; drag a pinned thread down into the active
69	list to unpin it. Dragging a thread onto the **Settled** header settles it, and dragging a settled
70	thread into the active list un-settles it. A snoozed thread can be dragged out of the snoozed
71	shelf, which wakes it, but threads cannot be dragged into the shelf because snoozing needs a wake
72	time. Dragging a pinned thread out of the pinned section does not ask for unpin confirmation.
73	Pinned and active boundary labels appear only while dragging, without moving the rows. The
74	other rows slide aside to show where the thread will land. When you cross into another section,
75	the dragged thread shows the action the drop performs, with its icon: **Pin**, **Unpin**,
76	**Settle**, **Un-settle**, or **Wake**. Its status and hover actions hide during the drag. A pinned
77	thread keeps its pin only while it stays in the pinned section; once it leaves, the badge takes
78	over. Reordering within the same section shows no badge. When there are no pins, drag to the top
79	edge to pin a thread. Section labels stay readable for the whole drag, and the section the
80	thread is over takes the accent color. Section labels also
81	identify empty sections and a collapsed settled shelf.
82
83	Drag within the pinned or active section to change its order. Other rows slide aside to show the
84	spot where the thread will land. Drops into either section keep the position you choose. On
85	mobile, open a thread's menu and choose **Arrange threads**. Drag a handle within or between
86	**Pinned** and **Active** to reorder, pin, or unpin. Drop onto the **Settled** divider to
87	settle a thread. The dragged card shows the action before you release it. Expand **Snoozed**
88	or **Settled** to drag a parked thread back into either live section. Each drop saves; **Done** returns to the thread list.
89	**Move up** and **Move down** are also available in the thread menu. The server
90	saves the order, so it survives a refresh and appears on your other connected devices.
91
92	On web and desktop, the list also animates section changes made with thread actions such as
93	**Pin**, **Settle**, and **Snooze**. These transitions respect your system's reduced-motion
94	preference. While dragging, rows follow the insertion gap without replaying a second transition
95	after the drop.
96
97	New threads appear above the active threads you have arranged. Settling clears a thread's active
98	position, so using **Un-settle** returns it to the top. Pinning and snoozing preserve its active
99	position until you move it again. Thread activity does not change the order. The settled shelf
100	continues to use settlement time.
101
102	If dragging is unavailable for one environment, update the T3 Code server running in that
103	environment. Pinned and active reordering require server support. Threads from older servers keep
104	their default order until the server is updated.
105
106	To generate a fresh title from the conversation, open a thread's menu and choose
107	**Regenerate title**. The action is unavailable while title generation is in progress
108	or when the connected environment needs a server update.
109
110	Agents connected through T3 Code can use the same server-owned metadata workflow to
111	rename a thread, regenerate its title, or link and unlink a pull request. These changes
112	appear on web, desktop, and mobile without requiring the originating browser to remain
113	open.
114
115	### Fold working threads (beta)
116
117	Turn on **Settings → General → Working section (beta)** on web and desktop, or **Settings →
118	Thread behavior → Working section** on iOS and Android, to move threads that are working or
119	monitoring into a collapsed **Working** section below the active list. A thread returns to the top
120	of the active list when it finishes, fails, or needs an approval or answer. The Working section
121	lists the thread you last sent work to first. Pinned threads stay in the pinned section. Each
122	device keeps its own choice.
123
124	While this is on, the active list is ordered by when each thread last came back to you, so you
125	cannot drag or move threads within it. Your saved order returns when you turn it off.
126
127	## Settle finished work
128
129	Choose **Settle thread** from its menu to move finished work out of the active list
130	without deleting the conversation. **Un-settle thread** restores it to active work
131	and prevents automatic settlement until new activity resumes the usual rules.
132	Manually settling an idle thread dismisses unanswered async questions without
133	sending an answer or restarting the agent. Manual settlement closes all of the
134	thread's terminals and browser tabs, including running commands and playing media.
135	Running programs or open browser tabs ask for confirmation; empty chats and idle
136	shells settle directly. Terminal output stays in the conversation. Undo or
137	unsettling restores the chat, but cannot restart those commands or restore its tabs.
138	Other chats keep their own terminals and tabs, including in a shared workspace.
139	The workspace's detached dev server stops once no
140	active chat or pending work needs it; shared workspaces keep their server while
141	another chat is active.
142
143	To reclaim disk space from settled work, turn on **Run in the thread's worktree when the
144	thread settles** for one of the project's actions, or set `"runOnSettle": true` on a
145	`t3.json` script, for example `cargo clean`. It runs each time a thread in its own
146	worktree settles, manually or automatically. Threads in the project's main checkout skip it. Its terminal
147	closes when the command succeeds and stays open when it fails.
148
149	Settled threads archive on Saturday at 9:00 AM in the server's local time. If the
150	server was offline, it catches up when it starts. Threads with running work or
151	pending requests wait until that work finishes.
152
153	On web and desktop, right-click **Settled** and choose **Archive all** to archive
154	the settled chats in the current project filter, including hidden chats. To archive
155	a selection, choose **Archive** from its context menu. Undo restores each archived
156	group together. Chats that resume work during Archive all stay available.
157
158	Workspaces for my work stay available while their chats are settled; settlement
159	does not run a cleanup script there. A settled work chat archives once all its
160	linked pull requests merge, including when you settle it after the merge.
161	Workspace cleanup waits for archival and for other chats or external tools
162	to release the folder. Mergebot supplies live PR and check updates. A new CI failure returns the chat to Active and adds a
163	Mergebot link to the transcript without starting an agent. Settling it again
164	acknowledges that failure; a failed rerun can wake it again.
165
166	On web and desktop, press a thread's **Settle** button and drag up or down to
167	settle every thread in that section between it and the one you release on.
168	The **Un-settle** and **Wake** buttons work the same way in their sections.
169	Press `Escape` while dragging to cancel.
170
171	By default, environments settle inactive threads after three days and settle
172	threads whose pull request merged. A closed pull request can also settle an idle
173	thread. Work in progress, pending questions or approvals, live background work,
174	and open terminals or browser tabs prevent automatic settlement. An open pull
175	request does not prevent inactivity settlement unless you turn on **Keep threads
176	with a PR** in **Settings → General**, but an old closed or merged pull request
177	does not settle work you
178	resumed after it closed. Only your own messages count as resuming. A turn that
179	finished background work or a pull request watch starts on its own does not.
180	Disconnected or unverified Mergebot data cannot trigger merge archival, PR-based
181	settlement, or a CI wakeup. Scheduled archival and inactivity rules still apply.
182
183	To keep one thread out of the settled shelf no matter how long it sits idle, open its menu,
184	choose **Auto-settle behavior**, and pick **Disabled**. The current option is checked. Pick
185	**Enabled** to return to the usual rules. Manual settle, snooze, and archive still work while it
186	is disabled.
187
188	Change these rules in **Settings → General** on web and desktop, or **Settings → Thread behavior** on mobile.
189	They continue to run when your apps are closed. On web and desktop, choose an environment at the
190	top to change only its rules, or **All environments** to update connected environments together.
191	Mixed values show where the selected environments disagree. Mobile applies these
192	rules to connected environments that support shared settings. Offline environments
193	and older servers keep their previous values. Changing a rule does not reopen
194	already settled threads.
195
196	## Link a pull request
197
198	The server finds the PR for each unsettled thread's saved branch, even when your
199	apps are closed. Settled threads keep their saved links. Update the server if
200	automatic branch links do not appear.
201
202	On web and desktop, right-click a pull request link in a thread and choose
203	**Link to thread** to select a different PR. Use **Unlink from thread** on the
204	same link to return to the branch PR, if one exists.
205	The linked pull request participates in automatic settlement.
206
207	## Find and reference work
208
209	On web and desktop, open the command palette with `Cmd/Ctrl+K` to search threads
210	across connected environments. Message search starts after two characters and
211	includes your messages and final agent responses.
212
213	Use **Settings → Keybindings** to find or customize shortcuts for searching files
214	and copying a thread reference. A copied reference uses the thread's pull request
215	link when available, otherwise its thread ID. See [keybindings](./keybindings.md)
216	for custom configuration.
217
218	## Inspect agent work
219
220	**Limited** means the provider stopped on a usage or rate limit. The conversation
221	keeps the provider's explanation. Retry after the limit resets, or switch to
222	another provider instance.
223	On web and desktop, press **Resume** in an empty composer to continue a limited
224	or interrupted turn manually.
225	Queued messages stay saved while the limit blocks the thread. They run after
226	the continuation finishes. If the queue was held by a restart, resume it then.
227
228	When the provider reports a reset time, choose **Resume at reset** to schedule a
229	continuation. You can cancel it from the thread. Enable **Auto-resume limited
230	threads** in **Settings → General** on web and desktop, or **Settings → Thread
231	behavior** on mobile, to schedule limit stops by default.
232	The environment must be running when the reset arrives; it resumes overdue
233	continuations after a restart. Sending a new message, archiving, or settling the
234	thread prevents a pending continuation from starting.
235
236	Choose **Snooze until reset** to hide the thread until its allowance returns.
237	Snooze and auto-resume are independent: snooze alone wakes the thread without
238	sending a message; enabling both wakes and continues it. **Wake now** cancels
239	the snooze. Enable **Snooze limited threads** in thread behavior settings to
240	snooze limit stops by default. Providers without a reset time offer manual
241	retry and the normal snooze choices.
242
243	On web and desktop, use **Agents** to follow work delegated to subagents.
244	Stop on a thread also stops the subagents it delegated to.
245
246	Subagent threads started by the agent can't take messages; message the parent
247	thread instead. When such a subagent needs an approval or an answer, the parent
248	thread asks for it.
249
250	Expand a tool call in the conversation to see its full command and output.
251	Summaries shorten shell wrappers and can still describe the latest call after it
252	finishes; the call's own result shows its status.
253
254	## Snooze until later
255
256	Choose **Snooze → Custom…** from a thread's menu to pick a date and time in your
257	local time zone, or a duration in minutes, hours, or days. Durations start when
258	you confirm; one day means 24 hours. On web and desktop, you can also snooze
259	several selected threads together. Choose **Wake thread** to bring a thread back early.