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