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
| 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. |