@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 375 lines 19.4 KB
Rendered Raw
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.