The best way to control Claude Code, Codex and more from any computer or phone
| 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. |