clover's git

the-knife

1	# Settings and project overrides
2
3	On web and desktop, the "Applying settings for …" sentence at the top of Settings pages picks
4	the project and environment a change applies to. Pages that only hold device preferences, such as
5	Appearance, don't show it. They start at **All projects** and **All environments**
6	and stay selected as you move between categories or search for a setting.
7
8	Preferences saved on this device, such as appearance, confirmations and browser profiles, always
9	show and ignore the selection. Everything else is stored on a server. Choose one environment to
10	edit its settings, or leave **All environments** to edit every connected environment at once.
11	Offline environments keep their current values; this is a bulk edit, not a synced global default.
12
13	Choose a project to override settings for it on the selected environments. A layers icon beside
14	each server row's title shows where the value comes from: the built-in default, the environment,
15	or a project override. Click it to see that chain on every selected environment. An override can
16	be reset to inherit again. Settings that cannot be overridden by a project are shown read-only
17	while a project is selected.
18
19	When the selected environments disagree, the control shows **Mixed** in place of a value and the
20	layers icon turns amber. Picking a value applies it to every selected environment.
21
22	Changing an environment value never touches a project's own override. When projects override the
23	setting you are editing, the layers icon counts them and the chain lists each one with its value:
24	click a project to jump to it, or **Reset all** to make those projects follow the environment
25	again.
26
27	Providers and diagnostics are per machine: they show one environment at a time, the primary
28	one until you pick another. Every other setting fans out to the selection.
29
30	With a project selected, a provider's switch in **Settings → Providers** turns it on or off for
31	that project only, in either direction: a provider off on the machine can be used in one project,
32	and one on everywhere can be kept out of another. That project's model pickers follow the switch,
33	and no new turn there can start on a provider it turned off, including queued messages and
34	follow-ups from delegated tasks. A turn already running when the switch flips finishes. A delegated
35	task's result still lands in its parent thread, which sees it on its next turn. Reset returns the project to the
36	machine's setting. Every other provider setting stays per machine.
37
38	On mobile, open **Settings** and use the filter in its header to choose connected environments
39	and a project. The filter stays available in server-setting pages. With **All projects** selected,
40	the **Server settings** categories and auto-settle controls in **Thread behavior** edit the
41	selected environments' defaults. Choosing a project edits its overrides on the selected
42	environments. Use **Use defaults** in a page to remove that page's project overrides.
43	Open **Settings → Projects & threads → Overview** to rename the project across its selected
44	connected checkouts and see where those checkouts live.
45	Settings that are environment-wide stay read-only while a project is selected. When selected
46	targets disagree, a control shows **Mixed** until you choose one value. Appearance, keyboard,
47	and other phone-only settings ignore the filter.
48
49	## Worktree branch names
50
51	In **Settings → Source Control → Worktree branch naming**, choose a static prefix,
52	a model-selected semantic prefix such as `feat/` or `fix/`, or custom instructions
53	for the complete name. The static prefix defaults to `t3/`; a trailing slash is
54	optional, and an empty prefix adds nothing. Invalid characters in a static prefix
55	are replaced with hyphens. Custom instructions are appended to
56	the naming prompt and can specify issue IDs, namespaces, and casing.
57
58	These settings apply to automatically named new worktree branches. Select a project
59	to override its environment defaults. Worktree directories keep their original names.
60	If generation fails, or a custom name is invalid or already taken, the temporary
61	branch name remains.
62
63	## Scheduled tasks on mobile
64
65	Open **Settings → Scheduled tasks** to create recurring tasks or manage existing
66	ones across your connected environments. Use the settings filter to narrow the
67	list by environment or project. Each task runs on the environment you choose,
68	using its project, model, and workspace settings. Fixed-time schedules use that
69	environment's time zone, which may differ from your phone's.
70
71	You can edit, pause, resume, run immediately, or delete a task from the list.
72	Webhook tasks only run when their URL is called, so they can't be run
73	immediately.
74	Leaving an edited form asks before discarding unsaved changes.
75
76	## Webhook automations
77
78	In **Settings → Scheduled tasks**, choose **On webhook**
79	as a task's schedule to run it whenever another service calls its URL, such as
80	GitHub on a new pull request or a CI job that failed. A public URL needs a
81	[T3 Connect](remote-access.md) managed tunnel; after you save the task, copy
82	its URL from the editor. Without one, the editor shows only the URL's path.
83	**Rotate** replaces the URL and the old one stops working.
84
85	The prompt decides what the agent sees. Placeholders pull values out of the
86	request: `{{body.path}}` for a JSON or form field, `{{headers.name}}`,
87	`{{query.name}}`, `{{body}}` for the raw body, and `{{request}}` for everything.
88	For example, `Review this PR: {{body.pull_request.html_url}}` sends only the
89	pull request link. A placeholder with no value is left empty.
90
91	For GitHub, turn on **Require signature**, keep the header
92	`x-hub-signature-256`, hex encoding and the `sha256=` prefix, and enter the
93	same secret in the repository's webhook settings with content type
94	`application/json`. Requests without a valid signature are rejected. Set this
95	up on desktop or web; mobile keeps an existing signature check but can't turn
96	one on.
97
98	On desktop and web, pick **Deliveries** from a task's menu to see recent
99	requests and the prompt each one produced.
100
101	If the environment is offline, the sender gets an error and nothing runs;
102	redeliver from the sender, such as GitHub's **Recent Deliveries**, once it is
103	back. To have T3 Connect keep requests instead, turn on **Hold webhooks while
104	offline** in **Settings → Connections**. T3 Connect then stores requests to a
105	T3 Connect URL for up to 24 hours and delivers them when the environment
106	returns. Leave it off if you don't want request bodies stored outside your
107	machine. To skip requests that waited too long, set **Skip requests older
108	than** on the task.
109
110	## Defaults and inheritance
111
112	General contains the model and workspace for new threads. Integrations controls agent browser
113	access. Source Control contains automatic pull, the default pull request merge method and text
114	generation. The same rows edit environment defaults or project overrides depending on the
115	project crumb.
116
117	The Project category, shown while a project is selected, holds the project's name, icon, actions,
118	checkouts and removal. Actions belong to a project: editing them creates the project's own list
119	on each selected environment, and reset returns to the environment's shared list. A project's
120	`t3.json` actions can be imported there.
121
122	Settings a repository can also declare in `t3.json`, such as the workspace for new threads,
123	resolve in one order: a project override, then the environment setting, then `t3.json`, then the
124	built-in default. Leave a setting on **Inherit** to let the next tier decide.
125	Browser access changes apply when an agent session next starts.
126
127	New worktrees initialize git submodules recursively. If that step is slow because the repository
128	declares many nested submodules, set **Submodules** in **Settings → General** (with the project
129	selected to override it there) to **Top level only** to stop at the ones the repository declares
130	itself, or **Skip** to leave them for a setup script. It resolves in the same order as the
131	workspace default: a `"worktreeSubmodules"` value in the `t3.json` of the branch being checked out
132	applies when the project and environment are both on **Inherit**.
133
134	## Worktree location
135
136	New worktrees go in the `worktrees` folder of the T3 home directory. To put them somewhere else,
137	such as another drive, set **Settings → Storage → Worktree location** to an absolute path like
138	`D:\worktrees` or `~/worktrees`. The setting is per machine. Existing worktrees stay where they
139	are, and cleanup covers both the default folder and the custom one.
140
141	## Storage cleanup
142
143	Open **Settings → Storage** to enable automatic cleanup on one machine or all connected
144	environments. Policies are off by default and run on the server at startup, when changed, and
145	hourly. Offline machines keep their existing policies.
146
147	Select a project to set **Automatic worktree cleanup** to **Inherit**, **Off**, or **Custom**.
148	Inherit follows each machine's rules; Off keeps that project's worktrees until you remove them
149	manually. Custom applies separate worktree rules to the selected project or checkout. Browser
150	captures and log retention remain machine-wide.
151
152	Worktrees can be removed after a chosen number of inactive days, after a thread settles, after
153	merging, or when they have no commits beyond the default branch. Set settled retention to 0 days
154	to remove a worktree at the next cleanup after settlement. Only T3-managed worktrees are eligible.
155	Active sessions and shared worktrees prevent removal. **Keep worktrees with local changes** defaults
156	to **Uncommitted changes**, which protects tracked edits and untracked files but deletes ignored
157	files such as `.env` and build output. **Any local files** also protects ignored files other than
158	`node_modules`. **Edited tracked files** protects only tracked edits and allows untracked and
159	ignored files to be deleted. Branches and thread history stay; starting another turn recreates the checkout.
160	Merge cleanup requires a merged pull request whose commits are included in the remote default
161	branch. A squash or rebase merge on GitHub also counts when the pull request targeted the default
162	branch and the worktree is still at the pull request's last commit.
163
164	Enable **Delete worktrees with deleted threads** to remove safe worktrees after their last
165	thread is deleted, including archived threads and worktrees left by earlier deletions. The
166	server waits for sessions and terminals to stop and retries skipped worktrees after restart.
167	Existing prompts for deleting a worktree manually remain available when this policy is off.
168
169	Choose **Delete now** to run the enabled rules immediately. The latest results show which
170	worktrees were removed or kept and why, plus any failures.
171
172	Browser captures and rotated logs have separate retention periods. Expired capture links stop
173	working. Current logs, message attachments, and browser profiles are kept.
174
175	## Project icons
176
177	Select the project and open Project to choose an icon, emoji, monogram, or image. The choice applies to
178	every checkout in the project group and appears on connected clients. Choose **Automatic** to let
179	T3 Code detect an icon again.
180
181	Choose **Monogram** in the icon picker to set one or two letters or numbers and a color.
182
183	When no image is found, web and desktop show a two-character monogram with a color
184	from the icon palette, derived from the saved project name. For example, `Nebula` becomes `NA`,
185	`Silver Orchard` becomes `SO`, and `M7 Forge` becomes `M7`.
186
187	## Keep the default branch current
188
189	In Source Control, enable **Automatically pull** to keep the default-branch checkout up to date
190	with its configured upstream. Choose an environment to set the default or a project to override it.
191	On mobile, use **Settings → Source control** to change selected environment defaults or project overrides.
192
193	T3 Code only pulls when it can fast-forward and the checkout has no changed files, untracked files,
194	or local commits. It skips checkouts on another branch or without an upstream. If a checkout has
195	local work, resolve it yourself before automatic pulls can resume.