1# Install T3 Code
2
3T3 Code runs coding agents on your computer and lets you control them from its
4desktop, web, or mobile app. Set up the machine where the agents will work first.
5
6## Requirements
7
8You need an installed, authenticated provider before starting a thread. You can
9launch T3 Code and configure providers afterwards.
10
11## Command line
12
14curl -fsSL https://t3.codes/install.sh | sh
16
17On Windows, in PowerShell:
18
20irm https://t3.codes/install.ps1 | iex
22
23This installs the `t3` binary to `~/.local/bin`. If that folder is not on your
24`PATH` yet, the installer says so and, for zsh, bash on Linux, and fish, prints
25a command to add it. On Windows, `t3` works in the same PowerShell window right
26away; add the folder to your `PATH` for new windows. If a `t3` that the
27installer or the desktop app did not create is already there, it leaves that
28one alone and stops. Set `T3CODE_CHANNEL=nightly` to install the nightly train, or
29`T3CODE_VERSION` to pin an exact version.
30
31| Task | Command |
32| ------------------------------------- | ----------------------------------------------------------------------- |
33| Start the server and open the web app | `t3` |
34| Start the server without a browser | `t3 serve` |
35| Use it from your other devices | `t3 up` ([details](./remote-access.md)) |
36| Keep it running in the background | `t3 service install` ([details](./background-service.md)) |
37| Move to the newest release | `t3 update` |
38| Reclaim database space | `t3 doctor` ([details](./background-service.md#reclaim-database-space)) |
39| Remove it again | `t3 uninstall` |
40
41Run `t3 help` or `t3 --help` for the full reference. To start in a new working
42directory, use an explicit path such as `t3 ./my-project`. A bare directory name
43is accepted only if it already exists.
44
45If `t3` or `t3 start` reports an already running server, connect to that server
46instead. Stop it before starting a replacement, or use a different `--base-dir`
47for an independent server.
48
49To try T3 Code once without installing it, run `npx t3@latest` instead (needs
50Node.js for `npx`). It offers to install the `t3` command first. If you say no,
51it asks again at the next minor release, and `npx t3 install` installs it later.
52`npx t3` always runs the version npm picked, even when a `t3` is installed. On
53the nightly train, run your installed `t3` (for example `t3 connect`), not
54`npx t3`, which runs the latest stable release.
55
56### Intel Macs
57
58There is no `t3` executable for Intel Macs (the desktop app is available). To
59run a server there, build it from source with `vp`, which provides the Node version it needs
60([Install vp](../operations/development.md#first-checkout)):
61
63git clone https://github.com/pingdotgg/t3code
64cd t3code && vp i && vp run build:desktop
65node apps/server/dist/bin.mjs
67
68`t3 update` and the background service do not apply to a server run this way;
69update it with `git pull` and a rebuild.
70
71## Desktop app
72
73Download a release from [GitHub Releases](https://github.com/pingdotgg/t3code/releases),
74or use a package manager:
75
76| Platform | Install |
77| ------------------ | ------------------------------------------------------------ |
78| Windows | `winget install T3Tools.T3Code` |
79| Windows (Scoop) | `scoop install extras/t3code` |
80| macOS | `brew install --cask t3-code` |
81| Debian, Ubuntu | `sudo apt install ./T3-Code-*.deb` |
82| Arch Linux | `yay -S t3code-bin` |
83| Arch Linux nightly | `yay -S t3code-nightly-bin` |
84| Nix | `nix profile add github:NixOS/nixpkgs/nixos-unstable#t3code` |
85
86### Linux
87
88AppImage and `.deb` downloads are available for x86_64 and ARM64. Check your
89architecture with `uname -m`: for `x86_64`, choose a file ending in
90`x86_64.AppImage` or `amd64.deb`; for `aarch64`, choose `arm64.AppImage` or
91`arm64.deb`.
92
93To launch an AppImage, open a terminal in its download folder. Replace
94`T3-Code.AppImage` below with the exact filename you downloaded:
95
97chmod +x ./T3-Code.AppImage
98./T3-Code.AppImage
100
101The `.deb` updates itself like the other desktop builds. It asks for your
102password to install each update. If your desktop has no password prompt, the
103update fails. Download the new `.deb` and install it the same way.
104
105The AUR packages currently support x86_64 only; on ARM64, use the AppImage.
106Update AUR installs with your AUR helper, such as `yay -Syu`, instead of the
107in-app updater.
108
109### Nix (nixpkgs)
110
111T3 Code is maintained in [nixpkgs](https://github.com/NixOS/nixpkgs/tree/nixos-unstable/pkgs/by-name/t3/t3code).
112The command above installs from `nixos-unstable` and requires Nix 2.30 or later with
113`nix-command` and `flakes` enabled. Launch the desktop app with `t3code-desktop`;
114the package also includes the `t3` command.
115
116On NixOS, you can instead add the package to your system configuration, using
117a nixpkgs revision that includes `t3code`:
118
120environment.systemPackages = [ pkgs.t3code ];
122
123Apply the change with `sudo nixos-rebuild switch`. For Home Manager, add
124`pkgs.t3code` to `home.packages` and run `home-manager switch`.
125
126Update a profile installation with `nix profile upgrade t3code`. For NixOS or
127Home Manager, update your configuration's nixpkgs input or channel and rebuild.
128Nix manages both the desktop app and the bundled
129`t3` command; use Nix to update them instead of the in-app updater or `t3 update`.
130
131### The `t3` command
132
133The desktop app includes the `t3` command-line tool. A new install sets it up
134on first launch; after an update, or any time, choose **Install** next to
135**t3 command** in **Settings → About**. On macOS and Linux it adds a `t3` link
136in `~/.local/bin` (or `~/bin`); on Windows it adds the app's command folder to
137your `PATH`. Open a new terminal afterwards. If the folder is not on your
138`PATH`, **Add to PATH** on the Welcome page or in **Settings → About** adds one
139line to your shell's startup file. **Remove** takes it off, and the app does not
140add it again. If you already have another `t3`, it stays as it is.
141
142### Windows Subsystem for Linux
143
144Choose a WSL distro in **Settings → Sharing & access** to run agents and projects
145there. Install the provider CLIs inside that distro. T3 Code installs its own
146server runtime there automatically; the first launch after an app update can
147take longer.
148
149### Open a project from a terminal
150
151With the desktop app already running on the same machine:
152
154t3 app
156
157This opens a new thread for the current directory, adding the project if needed.
158Pass a path, such as `t3 app ../my-project`, to open another directory. It requires
159the desktop app, so a standalone server or an SSH session is not enough. If the
160command cannot reach the app, start or update the desktop app and try again.
161
162### Drop a folder on the sidebar
163
164Drag one or more folders from Finder, Explorer, or your file manager onto the
165sidebar. Each one opens as a project on this computer, the same as `t3 app`.
166Files dropped on a thread still attach to that thread. Browsers do not share
167folder paths, so in the web app use **Add project** instead.
168
169## Mobile app
170
171Install T3 Code from the
172[App Store](https://apps.apple.com/us/app/t3-code-remote-claude-more/id6787819824) or
173[Google Play](https://play.google.com/store/apps/details?id=com.t3tools.t3code).
174The phone connects to a server on another machine. Follow
175[remote access](./remote-access.md) to link it through T3 Connect or a pairing URL.
176
177Store links and QR codes are also available in **Settings → About → Mobile app**
178on web and desktop. The store apps work with both stable and Nightly servers. Test builds are optional:
179
180**iPhone and iPad:** TestFlight is invite-only.
181**Android:** download an APK from the
182 [Android beta releases](https://github.com/pingdotgg/t3code/releases?q=android-beta-).
183
184If the app crashes during launch, open Settings → Diagnostics on the next launch
185that succeeds. It lists startup crashes from the last 7 days with the error and
186component stack that store crash reports leave out. Copy the report and paste it
187into a GitHub issue. Error messages can quote values from the app, so read it over
188before sharing.
189
190## Providers
191
192Open **Settings → Providers** in the web or desktop app, select the environment,
193and enable the provider you want. Installation, login, and configuration belong
194to that environment's machine, even when you connect from a phone or another
195computer.
196
197| Provider | Install and authenticate |
198| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
199| Codex | [Connect with ChatGPT](./providers-codex.md#connect-with-chatgpt), or install [Codex CLI](https://developers.openai.com/codex/cli) and run `codex login`. |
200| Claude | Install [Claude Code](https://claude.com/product/claude-code), then run `claude auth login`. |
201| Cursor | Install [Cursor CLI](https://cursor.com/cli), then run `agent login`. |
202| Grok Build | Install [Grok Build CLI](https://x.ai/cli), then run `grok login`. |
203| Kiro | Install [Kiro CLI](https://kiro.dev/docs/cli/), then run `kiro-cli login`. |
204| OpenCode | Install [OpenCode](https://opencode.ai), then run `opencode auth login`. |
205| Antigravity | Install and sign in with Google from T3 Code's provider settings. |
206| Pi | Install [Pi](./providers-pi.md#set-up-pi) with Node.js 22.19 or newer, then run `pi` and `/login`. |
207| Muse Code | Install [Muse Code](https://dev.meta.ai/docs/muse-code) on the server, run `muse login`, then enable it in Settings → Providers. |
208| fx | Install [fx](https://fx.sh) with `curl -fsSL https://fx.sh/setup.sh \| bash`, then run `fx login`. |
209
210Provider CLIs must be on the server's `PATH`. If T3 Code cannot find one, set its
211**Binary path** in provider settings, especially when using a version manager.
212Cursor's executable is `cursor-agent`, although its login command is
213`agent login`. Codex connected through ChatGPT and Antigravity can use their
214managed runtimes without a `PATH` entry.
215
216T3 Code warns when a provider version has known compatibility problems with your
217release. Check **Settings → Providers** on that environment for the recommended
218version or range. When its package manager supports installing a specific version,
219you can install the recommendation there. Otherwise use the provider's installer
220on the environment's machine. An unlisted version is unverified.
221
222When a provider CLI is behind its latest release, its provider card shows the
223available version. **Update now** runs the installer that owns the CLI
224(Homebrew, mise, or a global npm, pnpm, Yarn, Bun, Volta, or Vite+ install), or
225the CLI's own update command when T3 Code cannot tell. Claude, Codex, and
226OpenCode installs T3 Code cannot identify stay manual: update them through the
227installer you used. T3 Code runs `mise upgrade`
228only for a tool your mise config requests as `latest` when the provider's binary
229path is a mise shim or under the tool's `installs/<tool>/latest` link; update a
230pinned version, or a path into one version's directory, through mise yourself.
231Update a CLI installed with Nix through Nix.
232Cursor and Antigravity update with T3 Code. Homebrew and Chocolatey installs
233compare against the version their package manager offers, which can trail the
234npm release; update Claude installed with Chocolatey through Chocolatey.
235
236The managed runtimes for Antigravity and for Codex connected through ChatGPT
237first install the release T3 Code tested. When T3 Code finds a newer compatible
238release, their setup in **Settings → Providers** offers an update.
239
240Add another provider instance for a separate account or configuration. Each
241instance can have its own environment variables, such as API keys or a custom
242base URL. Mark secret values as sensitive; after saving, T3 Code does not display
243their original values.
244
245For provider-specific setup and accounts, see [Codex](./providers-codex.md),
246[Claude](./providers-claude.md), [OpenCode](./providers-opencode.md),
247[Antigravity](./providers-antigravity.md), [Kiro](./providers-kiro.md),
248[Pi](./providers-pi.md), [Muse Code](./providers-muse.md), and [fx](./providers-fx.md).
249
250### Provider check timeouts
251
252If a provider works in its CLI but T3 Code reports a timeout while checking it,
253allow more time in the T3 server's environment. For example, give Codex and
254Claude readiness checks 60 seconds:
255
257T3CODE_CODEX_PROBE_TIMEOUT_MS=60000 T3CODE_CLAUDE_PROBE_TIMEOUT_MS=60000 t3 serve
259
260For a remote environment, set these on the machine running the T3 server.
261Keep them in your launcher or service configuration to retain them across
262updates, then restart the server. For systemd, add
263`Environment=T3CODE_CODEX_PROBE_TIMEOUT_MS=60000` under `[Service]` in a service
264override, reload systemd, and restart the service. Provider instances can also
265set their own overrides in Settings → Providers.
266
267Each variable extends that provider's readiness-probe deadlines; a phase whose
268default is already longer keeps its default. Providers with several phases can
269take longer than one deadline in total. Values must be whole milliseconds no
270greater than 2147483647; unset or invalid values keep the defaults.
271
272| Provider | Environment variable |
273| ------------------- | -------------------------------------- |
274| Codex | `T3CODE_CODEX_PROBE_TIMEOUT_MS` |
275| Claude | `T3CODE_CLAUDE_PROBE_TIMEOUT_MS` |
276| Cursor | `T3CODE_CURSOR_PROBE_TIMEOUT_MS` |
277| Antigravity | `T3CODE_ANTIGRAVITY_PROBE_TIMEOUT_MS` |
278| Grok | `T3CODE_GROK_PROBE_TIMEOUT_MS` |
279| Kiro | `T3CODE_KIRO_PROBE_TIMEOUT_MS` |
280| fx | `T3CODE_FX_PROBE_TIMEOUT_MS` |
281| Pi | `T3CODE_PI_PROBE_TIMEOUT_MS` |
282| Muse Code | `T3CODE_MUSE_PROBE_TIMEOUT_MS` |
283| OpenCode | `T3CODE_OPENCODE_PROBE_TIMEOUT_MS` |
284| ACP Registry agents | `T3CODE_ACP_REGISTRY_PROBE_TIMEOUT_MS` |
285
286Longer deadlines also take longer to report a stalled check. These overrides
287cover readiness and discovery, including OpenCode server startup. Usage and
288config enrichment retain their own shorter limits. Turn execution, package
289installation, update checks, and shutdown limits keep their existing behavior.
290
291## Next steps
292
293[Working with threads](./thread-sidebar.md): start tasks and organize parallel work.
294[Permission modes](./permission-modes.md): choose when agents ask before acting.
295[Remote access](./remote-access.md): connect from another device.
296[Running in the background](./background-service.md): keep a host available.
297[Updating T3 Code](./updating.md): update the app and connected servers.
298[Managed policy](./managed-policy.md): configure T3 Code for everyone on a machine.