The best way to control Claude Code, Codex and more from any computer or phone
| 1 | # Development |
| 2 | |
| 3 | ## First checkout |
| 4 | |
| 5 | T3 Code uses [Vite+](https://viteplus.dev/guide/). Install its global `vp` command: |
| 6 | |
| 7 | ```sh |
| 8 | curl -fsSL https://vite.plus | bash |
| 9 | ``` |
| 10 | |
| 11 | On Windows, in PowerShell: |
| 12 | |
| 13 | ```powershell |
| 14 | irm https://vite.plus/ps1 | iex |
| 15 | ``` |
| 16 | |
| 17 | `vp` provides the Node version pinned in `package.json` (Node 26), so no separate Node install is |
| 18 | needed. From the repository root: |
| 19 | |
| 20 | ```sh |
| 21 | vp i |
| 22 | vp run dev |
| 23 | ``` |
| 24 | |
| 25 | Open the pairing URL printed by the dev runner. The bare origin does not authenticate |
| 26 | a new browser. |
| 27 | |
| 28 | Prefer a container? See [Dev container](../internals/devcontainer.md) for VS Code and Codespaces setup. |
| 29 | |
| 30 | ## Forge mirror (optional) |
| 31 | |
| 32 | GitHub is the source of truth. [source.tanstack.com/@pingdotgg/t3code](https://source.tanstack.com/@pingdotgg/t3code) |
| 33 | is a two-way synced mirror built for many agents working at once. You never need it to contribute. |
| 34 | |
| 35 | ```sh |
| 36 | git remote set-url origin https://source.tanstack.com/@pingdotgg/t3code.git |
| 37 | git remote add github https://github.com/pingdotgg/t3code.git |
| 38 | src auth login --web && src auth setup-git |
| 39 | ``` |
| 40 | |
| 41 | With `origin` on the mirror, use `src` (it takes `gh`'s commands and flags) and its `source` agent |
| 42 | skill for PRs, issues, reviews, and CI, and leave GitHub's API alone. Pull requests into `main` |
| 43 | merge on GitHub, so GitHub's required checks and reviews still apply. Numbers can differ between |
| 44 | the two forges; in text that reaches GitHub, use the GitHub number. |
| 45 | |
| 46 | ## Choosing a dev process |
| 47 | |
| 48 | Use `vp run dev` for server and web, or `vp run dev:desktop` for the Electron client. |
| 49 | `dev:server` and `dev:web` start those processes separately. |
| 50 | See the [mobile README](../../apps/mobile/README.md) for native builds and Metro. |
| 51 | |
| 52 | Flags go directly after the task name, for example `vp run dev --home-dir /tmp/t3code-dev`. |
| 53 | Add `--browser` to open a browser automatically. |
| 54 | |
| 55 | To stop a worktree's dev stack when its thread settles, import the **Dev** action from |
| 56 | `t3.json` in Settings > Projects > Actions and start it through the action menu or its |
| 57 | keybinding. Its `stopOnSettle` option lets T3 stop the terminal and its child processes. |
| 58 | Running `vp run dev` through an agent's own shell tool does not attach it to this lifecycle. |
| 59 | |
| 60 | ### State and ports |
| 61 | |
| 62 | Linked worktrees default to their own `.t3/userdata`, even when `T3CODE_HOME` is set. |
| 63 | Any other checkout, including the main checkout and every plain `git clone`, uses |
| 64 | `T3CODE_HOME` when it is set and otherwise `~/.t3/dev`, with default ports. Checkouts on |
| 65 | `~/.t3/dev` share one database, settings, and secrets, and only one of their servers can run |
| 66 | at a time. An explicit `--home-dir` wins in both cases. It and `T3CODE_HOME` store state in |
| 67 | `<home>/userdata`. |
| 68 | A home of `~/.t3`, from either source, still selects `~/.t3/dev`, because `~/.t3/userdata` is |
| 69 | the live install. |
| 70 | The first start in a worktree seeds its empty database from a read-only copy of |
| 71 | `~/.t3/userdata/statev2.sqlite` if the source is at most 500 MiB. Larger sources warn |
| 72 | and dev starts with an empty database. `--no-seed` or `T3CODE_DEV_SEED=0` skips seeding. |
| 73 | Seeding targets only a worktree's own `.t3`, so a plain clone or a `--home-dir` outside the |
| 74 | worktree starts empty. To give a clone its own seeded state, run |
| 75 | `vp run migrate-dev-db --base-dir <clone>/.t3` and then `vp run dev --home-dir <clone>/.t3`. |
| 76 | To copy a larger source, run `vp run migrate-dev-db` with dev stopped. It may use |
| 77 | substantial disk space before pruning. |
| 78 | The first start in any checkout also builds the native resource monitor with Cargo when |
| 79 | `native/resource-monitor/target` has no binary. Without Rust, dev starts with a warning |
| 80 | and no process telemetry; install Rust and run `vp run build:resource-monitor`. |
| 81 | Never run a development server against the live `~/.t3/userdata`. |
| 82 | See [test data](../../AGENTS.md#test-data) for copying a consistent database snapshot. |
| 83 | |
| 84 | Read ports from the `[dev-runner]` output. Worktrees derive stable preferences from their paths, |
| 85 | but occupied ports can shift them. `T3CODE_PORT_OFFSET` or `T3CODE_DEV_INSTANCE` can select a |
| 86 | different preference when needed. |
| 87 | |
| 88 | ### Replay provider |
| 89 | |
| 90 | `vp run dev` registers `Replay (dev)`, a local ACP agent at |
| 91 | [dev-replay-agent.ts](../../apps/server/scripts/dev-replay-agent.ts). It plays recorded |
| 92 | ACP transcripts with simulated streaming, so the real adapter, orchestration, and UI run |
| 93 | without a paid model. Each scenario is a model, and each prompt plays the next recorded turn. |
| 94 | Bundled servers, including desktop dev, skip it because they have no agent script. |
| 95 | Dev servers add it back on start, so turn it off in Settings instead of removing it. |
| 96 | To add a scenario, point a `SCENARIOS` entry at a generic ACP replay fixture |
| 97 | (`registry_transcript.ndjson`) or a file in [dev-replay](../../apps/server/scripts/dev-replay). |
| 98 | The agent replays session updates, permission requests, and questions. It drops session setup |
| 99 | and vendor frames, so Grok and fx recordings lose their vendor-only behavior. A `t3/mcp_call` |
| 100 | request frame (`{ name, arguments }`) makes the agent call that T3 tool itself over its MCP |
| 101 | session, and `<var:name>` in any frame is filled from the JSON file at `T3_DEV_REPLAY_VARS`. |
| 102 | |
| 103 | ### Profiling dev startup |
| 104 | |
| 105 | Run `vp run profile:startup` to capture the first 20 seconds of inherited Node processes under |
| 106 | `.t3/startup-profiles/<timestamp>`. Workers that execute the preload get separate profiles. |
| 107 | It starts the normal dev runner and accepts its flags. |
| 108 | Stop it with Ctrl+C after the capture. Set `T3CODE_STARTUP_PROFILE_DIR` to choose another output |
| 109 | directory. Profiling adds overhead, so compare readiness with an ordinary `vp run dev` run. |
| 110 | |
| 111 | Open a `.cpuprofile` in Chrome DevTools' Performance panel for sampled function stacks and source |
| 112 | lines. Each `.modules.json` is a Chrome trace containing timed module resolution, loading, |
| 113 | synchronous subprocess calls, and startup measures. Per-file records include importer URLs, |
| 114 | source loading, preparation, recursive dependency linking, and top-level evaluation. Preparation |
| 115 | uses synchronous loader boundaries; linking includes dependencies, and CommonJS evaluation can |
| 116 | include nested `require` calls. Some ESM/CommonJS interop reports a combined stage. `.process.json` records the process, Node version, and capture window. |
| 117 | The server's nested Effect and SQL spans remain in `.t3/userdata/logs/server.trace.ndjson`. |
| 118 | |
| 119 | The preload temporarily adds module-body timing markers and uses one automatic debugger pause |
| 120 | to instrument the live Node loader. The launcher adds `--no-node-snapshot` to inherited |
| 121 | `NODE_OPTIONS` because Node 26's snapshotted loader cannot accept that breakpoint. Include the |
| 122 | same flag when using the preload directly. This disables Node's built-in startup snapshot, |
| 123 | can change compilation-cache hits, and adds overhead. |
| 124 | Treat per-file captures as diagnostic runs; use uninstrumented runs for baseline startup latency. |
| 125 | The first entry module can compile before loader instrumentation is installed. |
| 126 | |
| 127 | A fresh process still uses filesystem, Node compilation, provider, and Vite dependency caches. |
| 128 | Measure a missing Vite dependency cache separately from a restart with an existing database. |
| 129 | Neither the Vite ready message nor the HTTP listener proves that a browser has rendered the app. |
| 130 | |
| 131 | ### Sharing and remote debugging |
| 132 | |
| 133 | `vp run dev --share` publishes the web port over the machine's tailnet and prints a pairing URL |
| 134 | for that origin. Give the tester the complete URL, including its token. The dev runner removes |
| 135 | its mapping on exit. |
| 136 | |
| 137 | Leave `VITE_HTTP_URL` and `VITE_WS_URL` unset. Vite proxies the backend through the browser's |
| 138 | origin so the same build works over localhost and remote connections. |
| 139 | |
| 140 | Shared runs enable bundled dev to avoid a network round trip for each import level. |
| 141 | `T3CODE_BUNDLED_DEV=0` opts out when debugging bundler differences. These traps matter |
| 142 | when changing this setup: |
| 143 | |
| 144 | - The web entry must dynamically import the app so React refresh initializes before application |
| 145 | chunks. Static imports can work on first load and fail after a route split. |
| 146 | - Bundled dev rebuilds Tailwind through watched files. Its ordinary Vite hot-update hook expects |
| 147 | a server/module graph that Rolldown does not provide. |
| 148 | - The app and its routes are lazy chunks, built on first request. A plugin pre-bundles the |
| 149 | startup chain when the server starts. Renaming or moving a startup route or the app entry |
| 150 | silently drops it from that list. |
| 151 | - Bundled dev and `--built` hand Rolldown its own watcher, which skips Vite's default |
| 152 | `node_modules` ignore. Those files are pnpm-store hardlinks, so another worktree's install or |
| 153 | removal rebuilds every long-running server and leaks memory. Keep `node_modules` excluded. |
| 154 | |
| 155 | The workarounds live in the [web entry](../../apps/web/src/bootstrap.ts), |
| 156 | [Tailwind plugin](../../apps/web/vite/tailwind.ts), and |
| 157 | [startup warmup](../../apps/web/vite/warmBundledDev.ts). |
| 158 | |
| 159 | `vp run dev --share --built` skips the Vite dev server. It runs `vp build --watch` for the web |
| 160 | app, and the backend serves `apps/web/dist` on the same tailnet URL and pairing flow. Use it when |
| 161 | someone tests over a slow link or only needs to use the app: loads are production size, and the |
| 162 | first load does not wait for dev bundling. There is no HMR. After an edit, wait for the |
| 163 | `built in` line (about 6 s), then reload. Until the first build exists, the URL shows a page that |
| 164 | reloads by itself. The license manifest is not generated in this mode. `--built` requires |
| 165 | `--share` and the `dev` mode. |
| 166 | |
| 167 | #### Reusable dev credential |
| 168 | |
| 169 | Use this only on a hostname where you trust every service. Browsers send cookies to all ports |
| 170 | on that hostname. Any service you visit there can receive the reusable admin credential, |
| 171 | including services unrelated to T3 Code. If you run untrusted services on that hostname, keep |
| 172 | normal per-environment pairing instead. |
| 173 | |
| 174 | To use one browser profile across web dev worktrees on the same hostname, generate one fixed |
| 175 | value once: |
| 176 | |
| 177 | ```sh |
| 178 | openssl rand -hex 32 |
| 179 | ``` |
| 180 | |
| 181 | Put that value in the main checkout's gitignored `.env`: |
| 182 | |
| 183 | ```dotenv |
| 184 | T3CODE_DEV_AUTH_TOKEN=<the value generated above> |
| 185 | ``` |
| 186 | |
| 187 | The `t3.json` Setup Worktree action links that file to each worktree's `.env`. The dev runner reads repository env files at startup. `.env.local` and inherited process |
| 188 | environment values override `.env`, so no per-worktree export is needed after setup. |
| 189 | |
| 190 | For a manual worktree or launcher without that link, export the same fixed value instead: |
| 191 | |
| 192 | ```sh |
| 193 | export T3CODE_DEV_AUTH_TOKEN="<the value generated above>" |
| 194 | ``` |
| 195 | |
| 196 | Do not generate a new value at startup. Start or restart `vp run dev --share` after configuration, |
| 197 | then open its printed startup pairing URL once per browser profile on that hostname. Later web dev |
| 198 | servers on the same hostname accept the shared cookie across ports. The cookie expires after 30 |
| 199 | days. Reload an old tab if its URL now serves a replacement environment. |
| 200 | |
| 201 | The token and startup pairing URLs are reusable administrative secrets. Never put them in a |
| 202 | commit, pull request, or public output. Every server still seeds its own auth database record at |
| 203 | startup and keeps its own SQLite data, signing key, and revocation state. Desktop and non-dev |
| 204 | servers ignore the value. See [environment authentication](../internals/environment-auth.md#reusable-dev-credential) |
| 205 | for the security model. |
| 206 | |
| 207 | ## Checks |
| 208 | |
| 209 | `vp run check:changed` runs CI's fast checks for your branch's changes: format and lint of the |
| 210 | changed files, `knip:check` when code or a manifest changes, the generated GraphQL checks, typecheck |
| 211 | of the affected packages and their dependents, and the test files beside the changed files. It also |
| 212 | runs the checks that read other files: the agent context budget when the server is affected, and |
| 213 | React Compiler coverage for only the changed web and mobile files. It maps |
| 214 | files to packages with [ci-changes.cjs](../../.github/scripts/ci-changes.cjs), as CI does. It |
| 215 | compares against the closest merge base with any remote's `main`, so a fork whose `main` lags |
| 216 | upstream still compares against upstream, or with a ref you pass. CI still runs the full |
| 217 | test suites and the jobs the summary lists, so a local pass does not promise a green CI run. |
| 218 | |
| 219 | The steps run side by side, as many at once as the machine allows: one per two cores and per 6 GiB |
| 220 | of available memory. On a large machine a run takes about as long as its slowest step, usually |
| 221 | knip's exports pass at about 10 s. Pass `--concurrency <n>` or set `CHECK_CHANGED_CONCURRENCY` to |
| 222 | change the limit (`1` runs the steps one by one). A step that runs past `--timeout <seconds>` or |
| 223 | `CHECK_CHANGED_TIMEOUT` (default 900) is killed with every process it started and reported as |
| 224 | `TIMEOUT`, not as a failing check. When the files are exactly those of the last passing run, it prints that |
| 225 | run's summary instead of running again. Any change to a file, the install, or a generated file runs |
| 226 | the checks again. |
| 227 | |
| 228 | While you iterate, run single checks: |
| 229 | |
| 230 | ```sh |
| 231 | vp test run <files> |
| 232 | vp lint <files> |
| 233 | vp run --filter <package> typecheck |
| 234 | ``` |
| 235 | |
| 236 | In `apps/web`, a test that renders React or touches the DOM is named `*.browser.test.{ts,tsx}` |
| 237 | and runs in headless Chromium with the React Compiler on, like the app. There is no jsdom; other |
| 238 | `*.test.ts` files run in Node. |
| 239 | |
| 240 | TypeScript workspaces typecheck with `effect-tsgo tsrs --noEmit` from `@effect/tsgo`: the |
| 241 | [tsrs](https://github.com/oxc-project/tsrs) checker with Effect diagnostics, quick fixes, and |
| 242 | refactors built in. Only `apps/marketing` installs `typescript`, for Astro. VS Code's TypeScript 7 |
| 243 | extension starts the same checker through `.vscode/tsdk/tsgo` (`js/ts.tsdk.path`), a POSIX |
| 244 | script, so on Windows open the workspace through WSL. |
| 245 | |
| 246 | Use `vp run lint:mobile` for native mobile changes. CI owns the full suite; see |
| 247 | [ci.yml](../../.github/workflows/ci.yml) for its current jobs. |
| 248 | The [manual Windows lane](../../.github/workflows/windows-tests.yml) is available for focused |
| 249 | Windows investigation while that suite is not a required gate. |
| 250 | |
| 251 | ### Unused code |
| 252 | |
| 253 | `vp run knip:check` checks unused files and dependencies across the repo and, at the same time, |
| 254 | unused runtime exports in `apps/server`, `apps/desktop`, `apps/web`, and every internal package under |
| 255 | `packages/`. CI enforces both checks. |
| 256 | Exported types and Effect schemas are allowed without consumers. The schema preprocessor |
| 257 | recognizes schema types, including aliases and schema classes; functions that create or decode |
| 258 | schemas remain checked. Canonical Effect service construction APIs stay exported with an explicit |
| 259 | `@public` annotation, which Knip recognizes. Completely unused files remain checked too. |
| 260 | Named exports in web UI component modules are kept as complete component sets. Knip ignores |
| 261 | unused exports in `apps/web/src/components/ui/*.tsx`, while still reporting an entire unused file. |
| 262 | Use `vp run knip --workspace apps/web` to audit one workspace, including exports, |
| 263 | or `vp run knip:production --workspace apps/web` to find code kept alive only by tests. |
| 264 | The full export audit still has findings and is not a repo-wide CI gate. Extend the |
| 265 | export check's workspace selectors as more workspaces become clean. Review callers before |
| 266 | deleting code; production mode can also report development scripts and test fixtures. |
| 267 | Runtime-discovered entrypoints and dependency exceptions belong in [knip.jsonc](../../knip.jsonc). |
| 268 | |
| 269 | ## Desktop artifacts |
| 270 | |
| 271 | Local artifact builds are unsigned by default and write to `release/`: |
| 272 | |
| 273 | ```sh |
| 274 | vp run dist:desktop:dmg |
| 275 | vp run dist:desktop:linux |
| 276 | vp run dist:desktop:win |
| 277 | ``` |
| 278 | |
| 279 | `dist:desktop:linux` targets x64. For a native Linux ARM64 build, run: |
| 280 | |
| 281 | ```sh |
| 282 | vp run dist:desktop:artifact --platform linux --target AppImage --arch arm64 |
| 283 | ``` |
| 284 | |
| 285 | DMGs default to the host architecture. Use `--arch` to choose another target and `--keep-stage` |
| 286 | to retain packaging files for inspection. Run `vp run dist:desktop:artifact --help` for other |
| 287 | options. |
| 288 | |
| 289 | ### Prepared server bytecode |
| 290 | |
| 291 | Native macOS and Windows desktop artifact builds, and native Linux x64 and ARM64 builds, generate server |
| 292 | bytecode with the packaged Electron executable, after ASAR creation and before signing. Generation imports the CLI and server |
| 293 | module declarations without launching server services; worker-only modules compile normally. |
| 294 | AppImage backends use temporary links for each mount and remove them on normal exit. Later launches |
| 295 | reclaim abandoned cache directories whose links point to gone mounts; AppImage main-process caching |
| 296 | stays disabled. macOS x64 builds on ARM64 hosts run the packaged x64 Electron |
| 297 | under Rosetta to generate the cache. Other cross-platform and cross-architecture builds skip |
| 298 | generation explicitly. CLI, SEA and WSL runtimes keep their existing behavior. |
| 299 | |
| 300 | Electron's Node 24 cache has no read-only option and includes the producer UID in its directory |
| 301 | name. The backend links individual prepared files into its writable cache with keys for the |
| 302 | installed module paths. Node replaces files atomically, so regeneration cannot write through those |
| 303 | links into signed resources. Windows uses hard links and falls back to normal caching when volumes |
| 304 | differ or resource permissions prevent linking. Protected installations therefore may not reuse |
| 305 | prepared bytecode. No cache bytes are copied during startup. |
| 306 | |
| 307 | The key calculation follows Node's internal portable ESM format. Generation checks that the |
| 308 | packaged engine produced the expected CLI and server entries and fails the build if that format changes. |
| 309 | The manifest also checks Electron, Node, OS, architecture and V8's flags-sensitive version tag. |
| 310 | Missing or rejected entries compile from the shipped JavaScript. Prepared backends skip the |
| 311 | explicit startup flush; Node can persist missing entries on normal exit. The writable fallback |
| 312 | keeps the explicit flush needed when Windows force-kills the backend. |
| 313 | |
| 314 | ### Linux AppImage prerequisites |
| 315 | |
| 316 | Build on Linux because the browser-secret helper links against the host's libsecret. Install |
| 317 | C/C++ build tools, libsecret development headers, pkg-config, and ImageMagick. |
| 318 | Bytecode preparation also runs packaged Electron and requires GTK, NSS, ALSA, and GBM runtime libraries. |
| 319 | Install Rust 1.95 or newer through [rustup](https://rust-lang.org/install), using the stable |
| 320 | toolchain as release CI does. |
| 321 | The packaged ELF compatibility check uses binutils’ `readelf`, included by the C/C++ toolchain. |
| 322 | |
| 323 | Ubuntu 24.04 and Debian 13: |
| 324 | |
| 325 | ```sh |
| 326 | sudo apt-get update |
| 327 | sudo apt-get install build-essential libsecret-1-dev pkg-config imagemagick libgtk-3-0t64 libnss3 libasound2t64 libgbm1 |
| 328 | ``` |
| 329 | |
| 330 | On Ubuntu 22.04 and Debian 12, use `libgtk-3-0` and `libasound2` instead of the `t64` packages. |
| 331 | |
| 332 | Fedora: |
| 333 | |
| 334 | ```sh |
| 335 | sudo dnf install gcc gcc-c++ make libsecret-devel pkgconf-pkg-config ImageMagick gtk3 nss alsa-lib mesa-libgbm |
| 336 | ``` |
| 337 | |
| 338 | Arch Linux: |
| 339 | |
| 340 | ```sh |
| 341 | sudo pacman -S base-devel libsecret pkgconf imagemagick gtk3 nss alsa-lib mesa |
| 342 | ``` |
| 343 | |
| 344 | The C toolchain, pkg-config, and libsecret headers are also needed for Linux desktop development. |
| 345 | |
| 346 | ### macOS DMG prerequisites |
| 347 | |
| 348 | Install the Xcode Command Line Tools with `xcode-select --install` and install Rust. |
| 349 | For a cross-architecture or universal build, add the requested Rust targets: |
| 350 | |
| 351 | ```sh |
| 352 | rustup target add aarch64-apple-darwin x86_64-apple-darwin |
| 353 | ``` |
| 354 | |
| 355 | ### Windows installer prerequisites |
| 356 | |
| 357 | Install Rust, Python 3, and Visual Studio Build Tools with **Desktop development with C++**. |
| 358 | Include the Windows SDK and the MSVC build tools and Spectre-mitigated libraries for the target |
| 359 | architecture. Add its Rust target: |
| 360 | |
| 361 | ```powershell |
| 362 | rustup target add x86_64-pc-windows-msvc |
| 363 | # For an ARM64 installer: |
| 364 | rustup target add aarch64-pc-windows-msvc |
| 365 | ``` |
| 366 | |
| 367 | NSIS is downloaded by electron-builder. WSL support additionally needs the Linux CLI archive |
| 368 | passed as `--wsl-runtime`; see the |
| 369 | [release runbook](./release.md#windows-payload-topology-and-update-validation). |
| 370 | |
| 371 | ### Signing and passkeys |
| 372 | |
| 373 | Add `--signed` after configuring the platform credentials in the |
| 374 | [release runbook](./release.md). macOS passkeys need a signed, provisioned app; follow the |
| 375 | [Connect setup](./connect-setup.md#desktop-passkeys) for local signing and renderer HMR. |