# Development ## First checkout T3 Code uses [Vite+](https://viteplus.dev/guide/). Install its global `vp` command: ```sh curl -fsSL https://vite.plus | bash ``` On Windows, in PowerShell: ```powershell irm https://vite.plus/ps1 | iex ``` `vp` provides the Node version pinned in `package.json` (Node 26), so no separate Node install is needed. From the repository root: ```sh vp i vp run dev ``` Open the pairing URL printed by the dev runner. The bare origin does not authenticate a new browser. Prefer a container? See [Dev container](../internals/devcontainer.md) for VS Code and Codespaces setup. ## Forge mirror (optional) GitHub is the source of truth. [source.tanstack.com/@pingdotgg/t3code](https://source.tanstack.com/@pingdotgg/t3code) is a two-way synced mirror built for many agents working at once. You never need it to contribute. ```sh git remote set-url origin https://source.tanstack.com/@pingdotgg/t3code.git git remote add github https://github.com/pingdotgg/t3code.git src auth login --web && src auth setup-git ``` With `origin` on the mirror, use `src` (it takes `gh`'s commands and flags) and its `source` agent skill for PRs, issues, reviews, and CI, and leave GitHub's API alone. Pull requests into `main` merge on GitHub, so GitHub's required checks and reviews still apply. Numbers can differ between the two forges; in text that reaches GitHub, use the GitHub number. ## Choosing a dev process Use `vp run dev` for server and web, or `vp run dev:desktop` for the Electron client. `dev:server` and `dev:web` start those processes separately. See the [mobile README](../../apps/mobile/README.md) for native builds and Metro. Flags go directly after the task name, for example `vp run dev --home-dir /tmp/t3code-dev`. Add `--browser` to open a browser automatically. To stop a worktree's dev stack when its thread settles, import the **Dev** action from `t3.json` in Settings > Projects > Actions and start it through the action menu or its keybinding. Its `stopOnSettle` option lets T3 stop the terminal and its child processes. Running `vp run dev` through an agent's own shell tool does not attach it to this lifecycle. ### State and ports Linked worktrees default to their own `.t3/userdata`, even when `T3CODE_HOME` is set. The main checkout defaults to `~/.t3/dev`. An explicit `--home-dir` wins in both cases. The first start in a worktree seeds its empty database from a read-only copy of `~/.t3/userdata/statev2.sqlite` if the source is at most 500 MiB. Larger sources warn and dev starts with an empty database. `--no-seed` or `T3CODE_DEV_SEED=0` skips seeding. To copy a larger source, run `vp run migrate-dev-db` with dev stopped. It may use substantial disk space before pruning. The first start in any checkout also builds the native resource monitor with Cargo when `native/resource-monitor/target` has no binary. Without Rust, dev starts with a warning and no process telemetry; install Rust and run `vp run build:resource-monitor`. Never run a development server against the live `~/.t3/userdata`. See [test data](../../AGENTS.md#test-data) for copying a consistent database snapshot. Read ports from the `[dev-runner]` output. Worktrees derive stable preferences from their paths, but occupied ports can shift them. `T3CODE_PORT_OFFSET` or `T3CODE_DEV_INSTANCE` can select a different preference when needed. ### Replay provider `vp run dev` registers `Replay (dev)`, a local ACP agent at [dev-replay-agent.ts](../../apps/server/scripts/dev-replay-agent.ts). It plays recorded ACP transcripts with simulated streaming, so the real adapter, orchestration, and UI run without a paid model. Each scenario is a model, and each prompt plays the next recorded turn. Bundled servers, including desktop dev, skip it because they have no agent script. Dev servers add it back on start, so turn it off in Settings instead of removing it. To add a scenario, point a `SCENARIOS` entry at a generic ACP replay fixture (`registry_transcript.ndjson`) or a file in [dev-replay](../../apps/server/scripts/dev-replay). The agent replays session updates, permission requests, and questions. It drops session setup and vendor frames, so Grok and fx recordings lose their vendor-only behavior. ### Profiling dev startup Run `vp run profile:startup` to capture the first 20 seconds of inherited Node processes under `.t3/startup-profiles/`. Workers that execute the preload get separate profiles. It starts the normal dev runner and accepts its flags. Stop it with Ctrl+C after the capture. Set `T3CODE_STARTUP_PROFILE_DIR` to choose another output directory. Profiling adds overhead, so compare readiness with an ordinary `vp run dev` run. Open a `.cpuprofile` in Chrome DevTools' Performance panel for sampled function stacks and source lines. Each `.modules.json` is a Chrome trace containing timed module resolution, loading, synchronous subprocess calls, and startup measures. Per-file records include importer URLs, source loading, preparation, recursive dependency linking, and top-level evaluation. Preparation uses synchronous loader boundaries; linking includes dependencies, and CommonJS evaluation can include nested `require` calls. Some ESM/CommonJS interop reports a combined stage. `.process.json` records the process, Node version, and capture window. The server's nested Effect and SQL spans remain in `.t3/userdata/logs/server.trace.ndjson`. The preload temporarily adds module-body timing markers and uses one automatic debugger pause to instrument the live Node loader. The launcher adds `--no-node-snapshot` to inherited `NODE_OPTIONS` because Node 26's snapshotted loader cannot accept that breakpoint. Include the same flag when using the preload directly. This disables Node's built-in startup snapshot, can change compilation-cache hits, and adds overhead. Treat per-file captures as diagnostic runs; use uninstrumented runs for baseline startup latency. The first entry module can compile before loader instrumentation is installed. A fresh process still uses filesystem, Node compilation, provider, and Vite dependency caches. Measure a missing Vite dependency cache separately from a restart with an existing database. Neither the Vite ready message nor the HTTP listener proves that a browser has rendered the app. ### Sharing and remote debugging `vp run dev --share` publishes the web port over the machine's tailnet and prints a pairing URL for that origin. Give the tester the complete URL, including its token. The dev runner removes its mapping on exit. Leave `VITE_HTTP_URL` and `VITE_WS_URL` unset. Vite proxies the backend through the browser's origin so the same build works over localhost and remote connections. Shared runs enable bundled dev to avoid a network round trip for each import level. `T3CODE_BUNDLED_DEV=0` opts out when debugging bundler differences. These traps matter when changing this setup: - The web entry must dynamically import the app so React refresh initializes before application chunks. Static imports can work on first load and fail after a route split. - Bundled dev rebuilds Tailwind through watched files. Its ordinary Vite hot-update hook expects a server/module graph that Rolldown does not provide. - The app and its routes are lazy chunks, built on first request. A plugin pre-bundles the startup chain when the server starts. Renaming or moving a startup route or the app entry silently drops it from that list. - Bundled dev and `--built` hand Rolldown its own watcher, which skips Vite's default `node_modules` ignore. Those files are pnpm-store hardlinks, so another worktree's install or removal rebuilds every long-running server and leaks memory. Keep `node_modules` excluded. The workarounds live in the [web entry](../../apps/web/src/bootstrap.ts), [Tailwind plugin](../../apps/web/vite/tailwind.ts), and [startup warmup](../../apps/web/vite/warmBundledDev.ts). `vp run dev --share --built` skips the Vite dev server. It runs `vp build --watch` for the web app, and the backend serves `apps/web/dist` on the same tailnet URL and pairing flow. Use it when someone tests over a slow link or only needs to use the app: loads are production size, and the first load does not wait for dev bundling. There is no HMR. After an edit, wait for the `built in` line (about 6 s), then reload. Until the first build exists, the URL shows a page that reloads by itself. The license manifest is not generated in this mode. `--built` requires `--share` and the `dev` mode. #### Reusable dev credential Use this only on a hostname where you trust every service. Browsers send cookies to all ports on that hostname. Any service you visit there can receive the reusable admin credential, including services unrelated to T3 Code. If you run untrusted services on that hostname, keep normal per-environment pairing instead. To use one browser profile across web dev worktrees on the same hostname, generate one fixed value once: ```sh openssl rand -hex 32 ``` Put that value in the main checkout's gitignored `.env`: ```dotenv T3CODE_DEV_AUTH_TOKEN= ``` 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 environment values override `.env`, so no per-worktree export is needed after setup. For a manual worktree or launcher without that link, export the same fixed value instead: ```sh export T3CODE_DEV_AUTH_TOKEN="" ``` Do not generate a new value at startup. Start or restart `vp run dev --share` after configuration, then open its printed startup pairing URL once per browser profile on that hostname. Later web dev servers on the same hostname accept the shared cookie across ports. The cookie expires after 30 days. Reload an old tab if its URL now serves a replacement environment. The token and startup pairing URLs are reusable administrative secrets. Never put them in a commit, pull request, or public output. Every server still seeds its own auth database record at startup and keeps its own SQLite data, signing key, and revocation state. Desktop and non-dev servers ignore the value. See [environment authentication](../internals/environment-auth.md#reusable-dev-credential) for the security model. ## Checks `vp run check:changed` runs CI's fast checks for your branch's changes: format and lint of the changed files, `knip:check` when code or a manifest changes, the generated GraphQL checks, typecheck of the affected packages and their dependents, and the test files beside the changed files. It also runs the checks that read other files: the agent context budget when the server is affected, and React Compiler coverage for only the changed web and mobile files. It maps files to packages with [ci-changes.cjs](../../.github/scripts/ci-changes.cjs), as CI does. It compares against the closest merge base with any remote's `main`, so a fork whose `main` lags upstream still compares against upstream, or with a ref you pass. CI still runs the full test suites and the jobs the summary lists, so a local pass does not promise a green CI run. The steps run side by side, as many at once as the machine allows: one per two cores and per 6 GiB of available memory. On a large machine a run takes about as long as its slowest step, usually knip's exports pass at about 10 s. Pass `--concurrency ` or set `CHECK_CHANGED_CONCURRENCY` to change the limit (`1` runs the steps one by one). A step that runs past `--timeout ` or `CHECK_CHANGED_TIMEOUT` (default 900) is killed with every process it started and reported as `TIMEOUT`, not as a failing check. When the files are exactly those of the last passing run, it prints that run's summary instead of running again. Any change to a file, the install, or a generated file runs the checks again. While you iterate, run single checks: ```sh vp test run vp lint vp run --filter typecheck ``` In `apps/web`, a test that renders React or touches the DOM is named `*.browser.test.{ts,tsx}` and runs in headless Chromium with the React Compiler on, like the app. There is no jsdom; other `*.test.ts` files run in Node. TypeScript workspaces typecheck with `effect-tsgo tsrs --noEmit` from `@effect/tsgo`: the [tsrs](https://github.com/oxc-project/tsrs) checker with Effect diagnostics, quick fixes, and refactors built in. Only `apps/marketing` installs `typescript`, for Astro. VS Code's TypeScript 7 extension starts the same checker through `.vscode/tsdk/tsgo` (`js/ts.tsdk.path`), a POSIX script, so on Windows open the workspace through WSL. Use `vp run lint:mobile` for native mobile changes. CI owns the full suite; see [ci.yml](../../.github/workflows/ci.yml) for its current jobs. The [manual Windows lane](../../.github/workflows/windows-tests.yml) is available for focused Windows investigation while that suite is not a required gate. ### Unused code `vp run knip:check` checks unused files and dependencies across the repo and, at the same time, unused runtime exports in `apps/server`, `apps/desktop`, `apps/web`, and every internal package under `packages/`. CI enforces both checks. Exported types and Effect schemas are allowed without consumers. The schema preprocessor recognizes schema types, including aliases and schema classes; functions that create or decode schemas remain checked. Canonical Effect service construction APIs stay exported with an explicit `@public` annotation, which Knip recognizes. Completely unused files remain checked too. Named exports in web UI component modules are kept as complete component sets. Knip ignores unused exports in `apps/web/src/components/ui/*.tsx`, while still reporting an entire unused file. Use `vp run knip --workspace apps/web` to audit one workspace, including exports, or `vp run knip:production --workspace apps/web` to find code kept alive only by tests. The full export audit still has findings and is not a repo-wide CI gate. Extend the export check's workspace selectors as more workspaces become clean. Review callers before deleting code; production mode can also report development scripts and test fixtures. Runtime-discovered entrypoints and dependency exceptions belong in [knip.jsonc](../../knip.jsonc). ## Desktop artifacts Local artifact builds are unsigned by default and write to `release/`: ```sh vp run dist:desktop:dmg vp run dist:desktop:linux vp run dist:desktop:win ``` `dist:desktop:linux` targets x64. For a native Linux ARM64 build, run: ```sh vp run dist:desktop:artifact --platform linux --target AppImage --arch arm64 ``` DMGs default to the host architecture. Use `--arch` to choose another target and `--keep-stage` to retain packaging files for inspection. Run `vp run dist:desktop:artifact --help` for other options. ### Prepared server bytecode Native macOS and Windows desktop artifact builds, and native Linux x64 and ARM64 builds, generate server bytecode with the packaged Electron executable, after ASAR creation and before signing. Generation imports the CLI and server module declarations without launching server services; worker-only modules compile normally. AppImage backends use temporary links for each mount and remove them on normal exit. Later launches reclaim abandoned cache directories whose links point to gone mounts; AppImage main-process caching stays disabled. macOS x64 builds on ARM64 hosts run the packaged x64 Electron under Rosetta to generate the cache. Other cross-platform and cross-architecture builds skip generation explicitly. CLI, SEA and WSL runtimes keep their existing behavior. Electron's Node 24 cache has no read-only option and includes the producer UID in its directory name. The backend links individual prepared files into its writable cache with keys for the installed module paths. Node replaces files atomically, so regeneration cannot write through those links into signed resources. Windows uses hard links and falls back to normal caching when volumes differ or resource permissions prevent linking. Protected installations therefore may not reuse prepared bytecode. No cache bytes are copied during startup. The key calculation follows Node's internal portable ESM format. Generation checks that the packaged engine produced the expected CLI and server entries and fails the build if that format changes. The manifest also checks Electron, Node, OS, architecture and V8's flags-sensitive version tag. Missing or rejected entries compile from the shipped JavaScript. Prepared backends skip the explicit startup flush; Node can persist missing entries on normal exit. The writable fallback keeps the explicit flush needed when Windows force-kills the backend. ### Linux AppImage prerequisites Build on Linux because the browser-secret helper links against the host's libsecret. Install C/C++ build tools, libsecret development headers, pkg-config, and ImageMagick. Bytecode preparation also runs packaged Electron and requires GTK, NSS, ALSA, and GBM runtime libraries. Install Rust 1.95 or newer through [rustup](https://rust-lang.org/install), using the stable toolchain as release CI does. The packaged ELF compatibility check uses binutils’ `readelf`, included by the C/C++ toolchain. Ubuntu 24.04 and Debian 13: ```sh sudo apt-get update sudo apt-get install build-essential libsecret-1-dev pkg-config imagemagick libgtk-3-0t64 libnss3 libasound2t64 libgbm1 ``` On Ubuntu 22.04 and Debian 12, use `libgtk-3-0` and `libasound2` instead of the `t64` packages. Fedora: ```sh sudo dnf install gcc gcc-c++ make libsecret-devel pkgconf-pkg-config ImageMagick gtk3 nss alsa-lib mesa-libgbm ``` Arch Linux: ```sh sudo pacman -S base-devel libsecret pkgconf imagemagick gtk3 nss alsa-lib mesa ``` The C toolchain, pkg-config, and libsecret headers are also needed for Linux desktop development. ### macOS DMG prerequisites Install the Xcode Command Line Tools with `xcode-select --install` and install Rust. For a cross-architecture or universal build, add the requested Rust targets: ```sh rustup target add aarch64-apple-darwin x86_64-apple-darwin ``` ### Windows installer prerequisites Install Rust, Python 3, and Visual Studio Build Tools with **Desktop development with C++**. Include the Windows SDK and the MSVC build tools and Spectre-mitigated libraries for the target architecture. Add its Rust target: ```powershell rustup target add x86_64-pc-windows-msvc # For an ARM64 installer: rustup target add aarch64-pc-windows-msvc ``` NSIS is downloaded by electron-builder. WSL support additionally needs the Linux CLI archive passed as `--wsl-runtime`; see the [release runbook](./release.md#windows-payload-topology-and-update-validation). ### Signing and passkeys Add `--signed` after configuring the platform credentials in the [release runbook](./release.md). macOS passkeys need a signed, provisioned app; follow the [Connect setup](./connect-setup.md#desktop-passkeys) for local signing and renderer HMR.