The best way to control Claude Code, Codex and more from any computer or phone

main
md 405 lines 24.5 KB
Rendered Raw
1 # Source control
2
3 T3 Code integrates with GitHub, GitLab, Forgejo, Gitea, Bitbucket, Azure DevOps, GitCafe, and Cursor
4 Origin to clone and publish repositories, create pull requests, and review changes.
5
6 ## Review turn changes
7
8 A turn's changed files and diff show only the turn's own work. When a turn pulls, merges, or
9 rebases, the files Git brought in are left out. A file stays in the list when the turn edited it,
10 committed it, or fixed a conflict in it. Use the branch comparison to review everything that changed
11 against your base branch. Restore still returns the complete saved workspace.
12
13 On web and desktop, open the Diff pane source picker and choose **Commits** to review one local
14 commit at a time. The list shows the newest 100 commits in the branch comparison. A merge commit
15 shows its changes against its first parent.
16
17 A commit link from a supported code host opens in the Diff pane when the thread's repository has
18 that commit locally, on any branch. Otherwise a pull request commit link opens the pull request. Other
19 commit links follow your **Open links in** setting; on web, when that opens a new tab, T3 Code first
20 shows an **Open link** button. Command/Ctrl+Click always opens the link in your browser. Commit links follow the **Open pull requests in T3 Code**
21 setting in **Settings → Diffs**.
22
23 ## Connect an account
24
25 Install Git and configure authentication on the machine running your T3 Code server. For a remote
26 environment, do this on the remote machine. After signing in, open **Settings → Source control & issues**
27 and choose **Rescan**.
28
29 ### GitHub
30
31 T3 Code talks to GitHub's API directly and only needs a token. Any of these works, in this
32 order of precedence:
33
34 1. A token saved in **Settings → Source control & issues → GitHub**. It is kept in the server's secret
35 store, and works without the GitHub CLI.
36 2. `GH_TOKEN` (`GH_ENTERPRISE_TOKEN` with `GH_HOST` for GitHub Enterprise Server) in the
37 server's environment.
38 3. [GitHub CLI](https://cli.github.com/) 2.81.0 or newer, signed in with `gh auth login`.
39
40 If `gh` is signed in to several accounts or hosts, expand **GitHub** in the same place to pick
41 the account each host uses or turn a host off. A saved token or `GH_TOKEN` takes precedence
42 over that choice; a host turned off stays off either way.
43
44 For GitHub Enterprise, sign in with `gh auth login --hostname YOUR_HOST`. T3 Code treats a
45 custom server name as GitHub once it has a credential for that host.
46
47 ### Forgejo and Gitea
48
49 Install [Forgejo CLI (`fj`)](https://codeberg.org/forgejo-contrib/forgejo-cli) or
50 [Gitea CLI (`tea`)](https://gitea.com/gitea/tea) 0.16 or later on your T3 Code server.
51 Sign in with `fj --host https://your-server auth add-token` or `tea login add`.
52 Repeat for each server you use, including Codeberg.
53
54 T3 Code prefers a matching `fj` login and falls back to `tea` when `fj` is unavailable
55 or has no login for that server. Once an account is selected, failed actions stay on that
56 account. Settings shows the detected CLI. Forgejo and Gitea share one integration entry.
57 Servers hosted under a URL subpath, such as `https://example.com/forgejo`, use `tea` because
58 fj does not preserve the subpath when checking its account.
59
60 When cloning or publishing, use a full repository URL to select a specific server.
61 You can use `owner/repo` when only one fj server is configured, or with your default `tea`
62 login when fj is unavailable or unconfigured. With multiple fj servers, use the full URL.
63 If you have multiple `tea` accounts on one server, select one with
64 `tea login default <login-name>`. Git push and clone also need Git credentials or an SSH key
65 for that server.
66
67 ### GitLab
68
69 Install [GitLab CLI](https://gitlab.com/gitlab-org/cli), then sign in:
70
71 ```bash
72 glab auth login
73 ```
74
75 ### Bitbucket
76
77 Open **Settings → Source control & issues**, expand **Bitbucket**, and enter one of:
78
79 - **Access token**: a token created for one repository, project, or workspace. It can only reach
80 what it was created for.
81 - **Atlassian account email** and **API token**: an Atlassian API token for your account. It can
82 reach every repository you can. Give it read/write access to repositories and pull requests, plus
83 user read access (`read:user:bitbucket`) and workspace read access (`read:workspace:bitbucket`).
84
85 A field saves when you leave it, and applies right away. The access token wins when both are saved.
86 Credentials are saved on the environment's server, so select a remote environment to configure
87 it. Saved tokens can't be viewed again; enter a new one to replace it, or choose **Remove** to clear
88 everything saved for Bitbucket.
89
90 If no credentials are saved, T3 Code falls back to these variables in the server's environment.
91 Restart the server after changing them:
92
93 ```bash
94 export T3CODE_BITBUCKET_ACCESS_TOKEN="your-access-token"
95 # or
96 export T3CODE_BITBUCKET_EMAIL="you@example.com"
97 export T3CODE_BITBUCKET_API_TOKEN="your-token"
98 ```
99
100 For a background service, put these `KEY=VALUE` entries in
101 [`service.env`](./background-service.md#configure-the-service-environment)
102 under T3 home, then run `t3 service restart`. Service installation and updates
103 preserve that file.
104
105 ### Azure DevOps
106
107 Install [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/), add the DevOps extension, and sign in:
108
109 ```bash
110 az extension add --name azure-devops
111 az login
112 ```
113
114 ### GitCafe
115
116 Install the GitCafe CLI and sign in:
117
118 ```bash
119 bun install -g @gitcafe/cli
120 cafe auth login --host https://git.cafe/api
121 ```
122
123 Alternatively, open **Settings → Source control & issues**, expand **GitCafe**, and enter a token. It is
124 kept in the server's secret store, applies right away, and is used before `CAFE_TOKEN` and the
125 `cafe` login. Or set `CAFE_TOKEN` in the server's environment and restart it. Both tokens are only
126 sent to `git.cafe`; `CAFE_TOKEN` follows `CAFE_HOST` if you set it. Repositories on
127 `staging.git.cafe` need their own login with `--host https://staging.git.cafe/api`.
128
129 Line comments are not available for GitCafe pull requests yet.
130 Merging a stack lands it through GitCafe, and updating a branch restacks the layers above it.
131
132 ### Cursor Origin
133
134 Install the [Origin CLI](https://cursor.com/docs/origin/cli) and sign in. Signing in also sets up Git
135 credentials for `origin.cursor.com`:
136
137 ```bash
138 curl -fsSL https://downloads.cursor.com/origin/install.sh | sh
139 origin auth login
140 ```
141
142 If cloning or pushing asks for a username, run `origin auth setup-git` to point Git at the CLI's
143 credentials again. Origin repositories use HTTPS and are published privately. Repositories mirrored
144 from GitHub keep their pull requests on GitHub; open those from the GitHub remote.
145
146 ## Start, clone, or publish a project
147
148 To start from nothing, choose **New project** in the command palette (`Cmd/Ctrl+K`), or
149 **New project** under **Add Project** on any client, and type a name. T3 Code makes a Git
150 repository in `~/.t3/projects` (the `projects` folder of your T3 data directory) with a README,
151 an icon, and a first commit, then opens a new thread in it. Until the project has a thread, new
152 threads work in its folder, even when your default is a new worktree. The folder is named after the project,
153 like `pinball-stats` for "Pinball Stats". Turn on **Create private repository on GitHub** to also
154 publish it. If Git has no name or email on that machine, the project is created without the
155 first commit.
156
157 Use **Add Project** in the command palette (`Cmd/Ctrl+K`) to clone a repository. Choose a hosting
158 provider or paste a Git URL, then choose where to save it. Only GitHub is listed at first. To list
159 another provider here and in **Publish Repository**, turn on its switch under
160 **Settings → Source control & issues**. A branch or file page copied from GitHub,
161 GitLab, GitCafe, Codeberg or Bitbucket also works: T3 Code clones that repository's default branch.
162 On other hosts, paste the repository's clone URL. The project opens right away while the
163 clone runs in the background: you can write your first prompt, and sending waits until the files
164 are in place. A toast tracks progress and lets you cancel; if the clone fails, retry it from the
165 toast or from the banner above the composer. When the host refuses the machine's SSH key, T3 Code
166 clones over HTTPS with Git's credentials for that host instead, and the project's remote uses the
167 HTTPS URL.
168
169 To lay clones out like [ghq](https://github.com/x-motemen/ghq), turn on **Clone into host folders**
170 under **Settings → Threads** (or **Source control** on mobile). Clones then default to
171 `<host>/<owner>/<repo>` under **Add project starts in**, so set that to `~/ghq` to share ghq's
172 folders. You can still change the destination before cloning.
173
174 For a local Git repository without a remote, **Publish Repository** creates a hosted repository,
175 adds it as `origin`, and pushes your commits. If there are no commits yet, it creates the remote;
176 make your first commit before pushing.
177
178 ## Create a pull request
179
180 Use a thread's Git actions to commit, push, and create a pull request. T3 Code can generate commit
181 messages, review titles, and descriptions from your changes. Descriptions also draw on the work in
182 the thread, including the checks it ran.
183
184 An existing fork PR can appear beside the branch even if you pushed without setting an upstream.
185 If its badge is missing because several remotes hold that branch, set the branch's upstream to
186 the intended remote with `git branch --set-upstream-to=<remote>/<branch>`.
187
188 Choose how commit messages and pull request titles and descriptions are written in
189 **Settings → Source control & issues → Commits & pull requests**. **Repository conventions** uses the
190 project's instructions and recent commit subjects. **Custom instructions** applies your own
191 instructions to commits and pull requests.
192
193 ## Review and merge
194
195 Open **Pull requests** to review changes and comments, request reviewers, check out a branch,
196 or merge. You can edit review titles and descriptions and your own comments where the host allows it.
197 Where you can edit a description, you can also tick its checkboxes from the Summary tab
198 (the Overview tab on mobile).
199 GitLab calls these merge requests.
200
201 Save a filter setup with **Views → Save current view** on the Pull Requests page. For example, choose
202 **Reviewing** (**Your review** on mobile) and save it as "PRs Requesting My Review". Choose a saved view to restore its search,
203 filters, sort order, and server/project scope. After changing filters, use **Update saved view** to
204 keep the changes, or save another view. You can also rename or delete views from the same menu.
205 Saved views stay in the browser or app where you created them and do not sync across devices.
206
207 A link to part of a pull request opens that part: a comment or review is marked in the activity, a
208 changed-line link opens the file at those lines, a checks link opens the checks, and a commit link
209 opens that commit's changes. On web and desktop, hovering a comment or commit link previews it.
210
211 On mobile, **Pull requests** lists reviews across your connected environments. Open a review
212 to read its description, activity, commits, and changed files. Line comments stay as drafts
213 until you submit the review. **Work on PR** opens a chat with the review attached; sending
214 the first message prepares a worktree from the review's branch.
215
216 Previously loaded lists, review details, guides, and diff pages remain readable on mobile
217 without a connection, including after restarting the app. Saved content refreshes when the
218 environment reconnects; submitting changes requires a connection.
219
220 Enable **Remove agent credits when merging** in Settings → Source control & issues to remove recognized
221 agent co-author and generated-by lines from GitHub merge and squash commit messages. Human
222 co-authors stay credited. The setting is off by default and projects can override it. It also
223 applies to auto-merge, but not merge queues or native stack merges. Original commits keep their
224 messages, so merge and rebase can still retain agent credits in those commits.
225
226 On web and desktop, hold **Shift** in the GitHub pull request list for quick actions.
227 To close several, press **Close**, drag across the rows in the same group, and release.
228 Press **Escape** before releasing to cancel. Failed closes stay in the list so you can retry them.
229
230 GitHub, GitLab, and Azure DevOps support auto-merge while checks are outstanding. GitHub also
231 supports approving waiting fork workflows and opening a revert pull request for a merged change.
232
233 Pull request sharing is off by default. In Settings → Environments → Pull request sharing (Pull
234 request routing under Environments on mobile), choose **Read PRs** or **Read and act** for each
235 environment you trust to share its source control access.
236 Enable both the original environment and the environment answering its requests on this client.
237 **Read and act** can use broader permissions than the original environment's credential;
238 only enable it for environments you control and trust. Changing a saved endpoint or removing an
239 environment clears its permission.
240
241 Review details, linked PR status, and permitted review actions can then use another connected
242 environment signed in to the same account on the same host. Each needs a project on that host.
243 A connected local environment is preferred for actions and can answer slow or failed reads.
244 Browsers and mobile clients need a paired environment to use its GitHub credentials.
245 Credentials stay on their machines. Previously verified credentials remain usable for routing
246 for ten minutes during a GitHub outage; new credentials must be verified first. An action with
247 an uncertain result is never automatically retried elsewhere. Listings, diffs, and checkout or
248 PR creation from Git actions continue to use the project's environment.
249
250 For Azure DevOps, use the host website to change comments. Bitbucket does not support reopening a
251 declined pull request.
252
253 ### Review guides
254
255 Review guides are in beta. Turn on **Review guides** in Settings → Source control & issues to add the
256 **Guide** tab to pull requests on that server. On mobile, move between stops with **Next**
257 and the back button; a stale guide offers a rewrite and hides excerpts that no longer match
258 the current change.
259
260 The **Guide** tab gives you a tour of a pull request without reading it line by line: stops
261 through the change in reading order. Each stop points at the lines worth reading, and a stop marked
262 **Look closely** has a call only a maintainer can make. Mechanical changes such as renames and
263 snapshots are grouped at the end, and every changed file appears somewhere on the tour.
264 Conversations already resolved in review are left out. For a pull request in a stack, the guide
265 covers that layer only, and may point out what a lower layer introduced or what a higher one uses.
266
267 Choose **Write guide** to have the review guide model from Settings → Source control & issues read the
268 change in a temporary checkout; without one set, the source control writer model is used. Nothing
269 in the checkout is changed, and a large pull request takes a few minutes; you can go elsewhere in
270 the app. On web, you are told when the guide is ready; on mobile, return to the guide to check
271 its progress. Claude and Codex can write guides. The guide is
272 kept for everyone using this server. To write it again, for example after a push or after changing
273 the model or instructions, choose **Rewrite guide** from the pull request's **⋯** menu.
274
275 On web, while reading a stop, select lines in an excerpt to add a comment to your review or ask an agent
276 about them; comments wait with the ones from the **Code** tab until you send the review. Choose a
277 suggested question, or **Ask about this stop**, to open a thread that already knows which stop you
278 are on. **Finish review** on the last stop opens the review with everything you collected.
279
280 Agents can write guides too: ask one to prepare guides for a set of pull requests, and it starts
281 them for you. Each is read through the project whose checkout has that repository.
282
283 To shape guides to your taste, write **Review guide instructions** in Settings → Source control & issues,
284 such as what to show first or what to skip; projects can override them. They change emphasis and
285 ordering, not the guide's layout or which files it covers.
286
287 ### Mark files as viewed
288
289 Tick a file off in the **Code** tab once you have read it and it collapses; the toolbar keeps a
290 running count. A tick belongs to the pull request rather than to a commit, so scoping the tab to a
291 single commit keeps them. A file pushed to after you cleared it comes back marked **Changed**.
292
293 On GitHub these are GitHub's own viewed marks, so a review carries between T3 Code and github.com
294 in either direction. Forgejo, GitLab, Bitbucket, Azure DevOps, and Cursor Origin expose no record
295 T3 Code can read, so the server you are connected to keeps them instead: they follow you across the
296 apps connected to that server, but the host's own site will not show them, and the count reads **viewed in T3 Code**.
297
298 On mobile, open a changed file and mark it viewed from its header. Viewed files collapse,
299 and their marks follow the same rules as on web and desktop.
300
301 ## Troubleshooting
302
303 - **Not authenticated:** run the provider's login command on the server, then rescan. For Bitbucket,
304 check the credentials saved in Settings → Source control & issues, or confirm the running server received
305 the environment variables.
306 - **GitHub sign-in cannot be verified:** update GitHub CLI to at least 2.81.0, or save a token in Settings → Source control & issues.
307 - **Push fails despite a connected account:** check the Git remote's credentials. SSH and HTTPS
308 remotes can require separate setup from the hosting provider's API access.
309 - **A review cannot load:** open it on the host website while resolving connectivity, permissions,
310 or rate limits.
311
312 ## Linked pull requests
313
314 A thread can hold several pull requests, including reviews from another repository on the same host.
315 Use **Link pull request** in the command palette or **Linked items** panel, or right-click a
316 pull request link in the conversation. Creating a pull request from Git actions links it automatically,
317 and so does an agent creating one with `gh pr create` or `glab mr create`. Agents can link other
318 pull requests with the `link_pull_request` tool.
319
320 Agents can also read, open, update, reply on, and merge pull requests in the thread's repository
321 through T3 Code's own tools, which use the same sign-in as the Pull requests page. An agent merges
322 only the commit it last read: if someone pushed since, the merge is refused. On github.com an
323 agent can also land a GitHub stack in one merge, like **Merge stack** below.
324
325 Use **Link pull request to thread** in the command palette to keep a pull request with the thread. From a review
326 on the Pull requests page, **Link to thread** lets you search for an active thread. The review header
327 also lists the threads that link to it, including archived threads, so you can return to their context.
328
329 Thread badges show a stack's layer count or the current review number with a count of additional
330 links. Clicking a badge with more than one review opens the **Linked items** panel. On mobile, the Git overview lists linked reviews and their stacks; tap a review to open it.
331 Linking and unlinking are available in the web and desktop clients.
332
333 The **Linked items** panel lists every review and groups stacks. Unlink a review from its
334 row menu. An unlinked stack layer stays out of later syncs. Open linked reviews refresh on the server;
335 closed reviews refresh periodically so reopening one on the host is detected. Merged reviews refresh
336 when requested. Settling a thread refreshes its open and closed reviews once; after that they stop refreshing until you unsettle it. With **Auto-settle merged threads** enabled, a thread can settle after every linked
337 review is terminal. An open or unsynced link keeps it active.
338
339 Ask the agent to watch, monitor, or babysit a pull request and it calls `watch_pull_request`. While
340 the thread is active, the server checks the pull request every two minutes and wakes the agent when a
341 check fails or waits for a maintainer's approval, the required checks pass, the other checks finish after a failure, someone else comments or reviews, or the branch starts to
342 conflict. On github.com it also wakes the agent, with GitHub's reason, when the merge queue drops
343 the pull request without merging it. Threads in a project that watch the same pull request share one check. On GitHub, a check
344 first asks whether anything changed and reads the pull request only when it did, which keeps
345 watching inside GitHub's rate limit. Comments from your own account do not wake it. When the pull
346 request merges or closes, watching ends, and the agent is woken once unless it merged or closed the
347 pull request itself with the host's CLI. A reopened pull request needs a new watch. Watching also ends after 10 wakes in a row that bring only comments, after 8
348 failed reads in a row, or when you press Stop on the thread. A rate limit only pauses watching.
349 Settling or archiving a thread also ends all its watches. Unsettle the thread before starting a new
350 watch. Watching a pull request again does not repeat check or conflict news its last
351 watch already reported; unlinking the pull request clears that. Subagents cannot watch pull requests; the thread that delegated to them does. To start or stop
352 it yourself, use the row menu in the **Linked items** panel. In the thread details card, a
353 watched pull request shows an eye; click it to stop watching.
354
355 A watched thread counts as working while the pull request still has checks running, so it stays in
356 the **Working** section, including after the agent pushes a fix. Once every check has finished,
357 including review bots that report as checks, the thread returns to your inbox: what happens next is
358 up to a person. That includes a workflow waiting for a maintainer to approve it, which runs only
359 once someone does. If you ask the agent to act on the pull request itself, such as merging it once
360 a teammate approves, the thread stays in **Working** until the pull request merges or closes. The
361 watch stays on and still wakes the agent on new comments, failed checks or conflicts, and a watched
362 thread never auto-settles.
363
364 Cross-repository links use a project on the same host. Azure DevOps reviews require a project checked
365 out from the matching organization and repository.
366
367 ## Issues
368
369 The Issues page lists the issues of every project whose remote is on GitHub, GitLab, Azure
370 DevOps or Forgejo, grouped per tracker account. Open it from the sidebar's utility row or with
371 **Open issues** in the command palette. Filter by open or closed, by your involvement
372 (assigned, opened by you, mentioning you), and by tracker. Under **Projects**, uncheck the
373 projects you do not want to see; the list remembers them, and a project you add later shows.
374 The search box asks the tracker itself where it can search. Press **Load more** at the end of a group to read further back.
375 The **Views** menu saves and restores a search, filter, and sort setup, as it does for pull
376 requests.
377
378 To list a Linear team's issues beside a project's, connect Linear with an API key under
379 Settings → Source control & issues, then choose the team for that project there.
380
381 Select an issue to open it beside the list: description, comments, state changes, linked pull
382 requests, labels, assignees, and reactions. Linked pull requests open in the same panel. You can
383 comment, edit the title and description, change labels and assignees, react, and close or
384 reopen (with a close reason where the tracker records one) when the tracker and your account
385 allow it. An issue read through a project that does not own its repository is shown read-only.
386
387 An issue can be kept with a thread the way a pull request can: open it beside the thread (issue
388 links in the conversation open there) and use **Link to this thread** in its header; **Unlink**
389 undoes it. Click the issue badge in the thread sidebar to see its issues and pull requests in
390 **Linked items**. Select an issue there to open it beside the thread. Agents link the issues they
391 work on with the `link_issue` tool.
392
393 Writing to a tracker over a remote connection requires the `source-control:write` scope.
394
395 ## GitHub stacks
396
397 The Pull requests page shows each PR's position in its GitHub stack. Open the stack badge in a
398 review to navigate its layers. **Merge stack** submits the selected pull request and every unmerged
399 layer below it to GitHub together, respecting branch rules and merge queues. The confirmation shows
400 the scope and merge strategy. GitHub rebases the remaining stack after merging.
401
402 **Rebase stack** updates remote branches from bottom to top without changing your local checkout.
403 It can rewrite history and restart checks. If a layer fails, earlier updates remain; resolve that
404 layer before retrying. GitHub may require manual conflict resolution after a lower layer is amended,
405 even when its changes look independent. Stack actions require an environment that supports them.