1# Settings and project overrides
2
3On web and desktop, the "Applying settings for …" sentence at the top of Settings pages picks
4the project and environment a change applies to. Pages that only hold device preferences, such as
5Appearance, don't show it. They start at **All projects** and **All environments**
6and stay selected as you move between categories or search for a setting.
7
8Preferences saved on this device, such as appearance, confirmations and browser profiles, always
9show and ignore the selection. Everything else is stored on a server. Choose one environment to
10edit its settings, or leave **All environments** to edit every connected environment at once.
11Offline environments keep their current values; this is a bulk edit, not a synced global default.
12
13Choose a project to override settings for it on the selected environments. A layers icon beside
14each server row's title shows where the value comes from: the built-in default, the environment,
15or a project override. Click it to see that chain on every selected environment. An override can
16be reset to inherit again. Settings that cannot be overridden by a project are shown read-only
17while a project is selected.
18
19When the selected environments disagree, the control shows **Mixed** in place of a value and the
20layers icon turns amber. Picking a value applies it to every selected environment.
21
22Changing an environment value never touches a project's own override. When projects override the
23setting you are editing, the layers icon counts them and the chain lists each one with its value:
24click a project to jump to it, or **Reset all** to make those projects follow the environment
25again.
26
27Providers and diagnostics are per machine: they show one environment at a time, the primary
28one until you pick another. Every other setting fans out to the selection.
29
30With a project selected, a provider's switch in **Settings → Providers** turns it on or off for
31that project only, in either direction: a provider off on the machine can be used in one project,
32and one on everywhere can be kept out of another. That project's model pickers follow the switch,
33and no new turn there can start on a provider it turned off, including queued messages and
34follow-ups from delegated tasks. A turn already running when the switch flips finishes. A delegated
35task's result still lands in its parent thread, which sees it on its next turn. Reset returns the project to the
36machine's setting. Every other provider setting stays per machine.
37
38On mobile, open **Settings** and use the filter in its header to choose connected environments
39and a project. The filter stays available in server-setting pages. With **All projects** selected,
40the server-setting pages, such as Threads, Source control and Worktrees, edit the selected
41environments' defaults. Choosing a project edits its overrides on the selected
42environments. Use **Use defaults** in a page to remove that page's project overrides.
43Open **Settings → Projects** to rename the project across its selected
44connected checkouts and see where those checkouts live.
45Settings that are environment-wide stay read-only while a project is selected. When selected
46targets disagree, a control shows **Mixed** until you choose one value. Appearance, keyboard,
47and other phone-only settings ignore the filter.
48
49## Pin and archive projects
50
51Pinned projects come first in the project pickers: the project picker on a new thread, the
52new-thread list, the command palette, the sidebar project filter, and mobile. In the boring sidebar, pinned projects get the top
53folders, even with no active threads. Pin or unpin a project from its row in any of those lists,
54or press the thread pin shortcut (`mod+shift+p` by default) on the highlighted row. **Pin
55project** in the command palette and **Settings → Projects** work too. A list keeps its order
56while it is open, so a new pin moves up the next time you open it.
57
58Archive a project you are done with in **Settings → Projects**. It leaves the project pickers.
59Its threads, settings, and files stay as they are, and archived projects still show in the
60Settings project list, marked **Archived**. Choose one there and select **Unarchive** to bring it
61back. On mobile, both are in **Settings → Projects → Organize**.
62
63A project on several machines must have every machine connected to pin or archive it.
64
65## Worktree branch names
66
67In **Settings → Worktrees → Worktree branch naming**, choose a static prefix,
68a model-selected semantic prefix such as `feat/` or `fix/`, or custom instructions
69for the complete name. The static prefix defaults to `t3/`; a trailing slash is
70optional, and an empty prefix adds nothing. Invalid characters in a static prefix
71are replaced with hyphens. Custom instructions are appended to
72the naming prompt and can specify issue IDs, namespaces, and casing.
73
74These settings apply to automatically named new worktree branches. Select a project
75to override its environment defaults. Worktree directories keep their original names.
76If generation fails, or a custom name is invalid or already taken, the temporary
77branch name remains.
78
79## Scheduled tasks on mobile
80
81Open **Settings → Scheduled tasks** to create scheduled tasks or manage existing
82ones across your connected environments. Use the settings filter to narrow the
83list by environment or project. Each task runs on the environment you choose,
84using its project, model, and workspace settings. Fixed-time schedules use that
85environment's time zone, which may differ from your phone's. Choose **Once**
86to run a task a single time at a date and time in your own time zone. If the
87environment is offline then, the task runs when it is back.
88
89Under **Destination**, choose where runs go. **New thread each run** keeps every
90run separate. The two one-thread choices start a thread on the first run and post
91later runs there: one continues the same conversation, the other starts each run
92in a fresh session that doesn't see earlier runs, so the thread stays readable
93without the agent's context growing. To move a one-thread task, pick another
94thread in its project under **Destination**. Moving such a task to another
95project starts a new thread there on its next run.
96
97Deleting a thread also deletes tasks that post into that thread. Tasks that start
98a new thread on each run survive deletion of their previous threads.
99
100You can edit, pause, resume, run immediately, or delete a task from the list.
101Webhook tasks only run when their URL is called, so they can't be run
102immediately.
103Leaving an edited form asks before discarding unsaved changes.
104
105## Webhook automations
106
107In **Settings → Scheduled tasks**, choose **On webhook**
108as a task's schedule to run it whenever another service calls its URL, such as
109GitHub on a new pull request or a CI job that failed. A public URL needs a
110[T3 Connect](remote-access.md) managed tunnel; after you save the task, copy
111its URL from the editor. Without one, the editor shows only the URL's path.
112**Rotate** replaces the URL and the old one stops working.
113
114The prompt decides what the agent sees. Placeholders pull values out of the
115request: `{{body.path}}` for a JSON or form field, `{{headers.name}}`,
116`{{query.name}}`, `{{body}}` for the raw body, and `{{request}}` for everything.
117For example, `Review this PR: {{body.pull_request.html_url}}` sends only the
118pull request link. A placeholder with no value is left empty.
119
120Each value reaches the agent wrapped in `<webhook-data-…>` tags and marked as
121untrusted request data. This helps the agent tell it apart from your
122instructions, but it doesn't guarantee the agent ignores what the text says.
123Inside a value, every `$`, other currency sign and `@`, and a `/` that starts
124a lone word, gets an invisible character after it, so mentions like `$skill`,
125`@file` and `/command` don't act. Text copied from a value, such as an email
126address or a command, carries that character too. Without a signature, anyone
127with the URL can start a run with any content. A signature only proves which
128service sent the request: a GitHub payload still carries text written by any
129GitHub user.
130
131For GitHub, turn on **Require signature**, keep the header
132`x-hub-signature-256`, hex encoding and the `sha256=` prefix, and enter the
133same secret in the repository's webhook settings with content type
134`application/json`. Requests without a valid signature are rejected. Set this
135up on desktop or web; mobile keeps an existing signature check but can't turn
136one on.
137
138To run only for some requests, add **Filters**. Each one tests a value named
139like a placeholder, without the braces, such as `headers.x-github-event` equals
140`pull_request` or `body.action` is one of `opened, reopened`. A task runs only
141when every filter matches; other requests are answered normally, logged as
142**Filtered** with the first filter that failed, and start nothing. Values
143compare as text, and a value that is an object or a list only passes
144**exists**. Separate **is one of** values with commas; a value can't contain
145a comma or start or end with a space.
146
147To suppress repeated deliveries, set a **Duplicate request key** template, such as
148`{{headers.delivery-id}}`. The same key is ignored for seven days per task.
149To combine a burst, set a **Coalesce key**, such as `{{body.id}}`, and a window
150of 10–3600 seconds (120 by default). One run uses the latest body, headers,
151and query when the window from the first delivery closes; later requests
152do not extend it. Pending windows survive a server restart. Keys must contain
153request placeholders; if any placeholder is missing, or the render is empty,
154that key's rule is skipped. Clear the templates to turn dedupe off.
155
156Duplicate and coalesced log entries share a limit of 10 per task per minute.
157Additional deliveries are accepted without a log entry, and coalesced deliveries
158always replace the persisted payload. Coalesced updates count toward a separate
15960-per-minute validation limit; exceeding it receives HTTP 429.
160
161On desktop and web, pick **Deliveries** from a task's menu to see recent
162requests and the prompt each one produced.
163
164If the environment is offline, the sender gets an error and nothing runs;
165redeliver from the sender, such as GitHub's **Recent Deliveries**, once it is
166back. To have T3 Connect keep requests instead, turn on **Hold webhooks while
167offline** in **Settings → Sharing & access**. T3 Connect then stores requests to a
168T3 Connect URL for up to 24 hours and delivers them when the environment
169returns. Leave it off if you don't want request bodies stored outside your
170machine. To skip requests that waited too long, set **Skip requests older
171than** on the task.
172
173## Defaults and inheritance
174
175Threads contains the model and workspace for new threads. Browser controls agent browser
176access. Source control contains automatic pull, the default pull request merge method and text
177generation. The same rows edit environment defaults or project overrides depending on the
178project crumb.
179
180The Projects category, under Code, holds the project's name, icon, actions,
181checkouts and removal. Actions belong to a project: editing them creates the project's own list
182on each selected environment, and reset returns to the environment's shared list. A project's
183`t3.json` actions can be imported there.
184
185Settings a repository can also declare in `t3.json`, such as the workspace for new threads,
186resolve in one order: a project override, then the environment setting, then `t3.json`, then the
187built-in default. Leave a setting on **Inherit** to let the next tier decide.
188Browser access changes apply when an agent session next starts.
189
190New worktrees initialize git submodules recursively. If that step is slow because the repository
191declares many nested submodules, set **Submodules** in **Settings → Worktrees** under Advanced (with the project
192selected to override it there) to **Top level only** to stop at the ones the repository declares
193itself, or **Skip** to leave them for a setup script. It resolves in the same order as the
194workspace default: a `"worktreeSubmodules"` value in the `t3.json` of the branch being checked out
195applies when the project and environment are both on **Inherit**.
196
197## Worktree location
198
199New worktrees go in the `worktrees` folder of the T3 home directory. To put them somewhere else,
200such as another drive, set **Settings → Worktrees → Worktree location** to an absolute path like
201`D:\worktrees` or `~/worktrees`. The setting is per machine. Existing worktrees stay where they
202are, and cleanup covers both the default folder and the custom one.
203
204## Fast worktree checkout on macOS
205
206Fast worktree checkout is a beta. Turn it on for each Mac in **Settings → Labs → Fast worktree
207checkout**. T3 Code then keeps a few recent checkouts of each repository in the `caches` folder of
208the T3 home directory. A new worktree is cloned from one of them with APFS copy-on-write, which is
209about twice as fast as writing every file and makes the first `git status` in it fast as well.
210Turning it off deletes the cache.
211
212The first worktree of a repository uses Git's normal checkout and fills the cache. It needs Git 2.42
213or newer. Git's normal checkout is also used for worktrees on a different drive from the T3 home
214directory, sparse checkouts, repositories whose attributes use filters such as Git LFS, and
215repositories whose checkout settings changed.
216
217## Storage cleanup
218
219Open **Settings → Worktrees → Cleanup** to enable automatic cleanup on one machine or all connected
220environments. Policies are off by default and run on the server at startup, when changed, and
221hourly. Offline machines keep their existing policies.
222
223Select a project to set **Automatic worktree cleanup** to **Inherit**, **Off**, or **Custom**.
224Inherit follows each machine's rules; Off keeps that project's worktrees until you remove them
225manually. Custom applies separate worktree rules to the selected project or checkout. Browser
226captures and log retention remain machine-wide.
227
228Worktrees can be removed after a chosen number of inactive days, after a thread settles, after
229merging, or when they have no commits beyond the default branch. Set settled retention to 0 days
230to remove a worktree at the next cleanup after settlement. In repositories without remotes,
231unchanged-worktree cleanup compares against the branch checked out in the project workspace;
232if that checkout has a detached HEAD, the worktree is kept. Only T3-managed worktrees are eligible.
233Active sessions and shared worktrees prevent removal. **Keep worktrees with local changes** defaults
234to **Uncommitted changes**, which protects tracked edits and untracked files but deletes ignored
235files such as `.env` and build output. **Any local files** also protects ignored files other than
236`node_modules`. **Edited tracked files** protects only tracked edits and allows untracked and
237ignored files to be deleted. Branches and thread history stay; starting another turn recreates the checkout.
238Merge cleanup requires a merged pull request whose commits are included in the remote default
239branch. A squash or rebase merge on GitHub also counts when the pull request targeted the default
240branch and the worktree is still at the pull request's last commit.
241
242Enable **Delete worktrees with deleted threads** to remove safe worktrees after their last
243thread is deleted, including archived threads and worktrees left by earlier deletions. The
244server waits for sessions and terminals to stop and retries skipped worktrees after restart.
245Existing prompts for deleting a worktree manually remain available when this policy is off.
246
247Choose **Delete now** to run the enabled rules immediately. The latest results show which
248worktrees were removed or kept and why, plus any failures.
249Results also list folders in the worktree folder that no thread uses, with their sizes; cleanup never removes them, so remove them manually if you want.
250
251Browser captures and rotated logs have separate retention periods. Expired capture links stop
252working. Current logs, message attachments, and browser profiles are kept.
253
254## Project icons
255
256Select the project and open Project to choose an icon, emoji, monogram, or image. The choice applies to
257every checkout in the project group and appears on connected clients. Choose **Automatic** to let
258T3 Code detect an icon again.
259
260Choose **Monogram** in the icon picker to set one or two letters or numbers and a color.
261
262When no image is found, web and desktop show a two-character monogram with a color
263from the icon palette, derived from the saved project name. For example, `Nebula` becomes `NA`,
264`Silver Orchard` becomes `SO`, and `M7 Forge` becomes `M7`.
265
266## Keep the default branch current
267
268In Source control, enable **Automatically pull** to keep the default-branch checkout up to date
269with its configured upstream. Choose an environment to set the default or a project to override it.
270On mobile, use **Settings → Source control** to change selected environment defaults or project overrides.
271
272T3 Code only pulls when it can fast-forward and the checkout has no changed files, untracked files,
273or local commits. It skips checkouts on another branch or without an upstream. If a checkout has
274local work, resolve it yourself before automatic pulls can resume.