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