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