@devries-cameron20 / t3code-1 / commits / 52c2b38ea4
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

docs: document the GitCafe mirror and refresh the dev setup (#23808)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Julius Marminge committed Oct 22, 2026 at 13:31 UTC 52c2b38ea41ee2271f5aca527009d36d25432689
6 files changed +52 -9
.devcontainer/devcontainer.json
+2 -2
@@ -1,4 +1,4 @@
1 -// Dev container for T3 Code. Mirrors CI (ubuntu-24.04, Node 24, Rust stable)
1 +// Dev container for T3 Code. Mirrors CI (ubuntu-24.04, Node 26, Rust stable)
2 // and the canonical setup in docs/operations/development.md: global `vp`, `vp i`.
3 // Contributor doc: docs/internals/devcontainer.md
4 {
@@ -8,7 +8,7 @@
8 // nodeGypDependencies (default true) brings python3/make/g++, which Linux
9 // needs for node-pty's node-gyp fallback (its prebuilds are mac/win only).
10 "ghcr.io/devcontainers/features/node:2": {
11 - "version": "24"
11 + "version": "26"
12 },
13 // native/resource-monitor (edition 2024, needs stable >= 1.85). The server
14 // degrades gracefully without the binary, but CI checks cargo fmt + test.
AGENTS.md
+1
@@ -139,6 +139,7 @@ For authorized mobile verification, a missing or outdated native client is a bui
139 ## Pull requests
140
141 - Never make a PR unless the developer explicitly asks you to do so.
142 +- If `origin` is git.cafe, follow [GitCafe mirror](docs/operations/development.md#gitcafe-mirror-optional): use `cafe` for existing PRs, issues, comments and labels, but push and open PRs on GitHub, where CI runs.
143 - Conventional commit titles, plain language: `fix(web): new threads no longer spike CPU`.
144 - Body: the problem in a sentence or two, then how you fixed it. End with the model and harness that did the work.
145 - UI changes need before/after images. Motion or timing needs a short video.
docs/internals/devcontainer.md
+1 -1
@@ -2,7 +2,7 @@
2
3 > For maintainers. Using T3 Code? See [docs/user](../user/).
4
5 -`.devcontainer/` gives you a ready-to-code Linux environment matching CI: Ubuntu 24.04, Node 24, pnpm, Rust stable, the global `vp` CLI, and the GitHub CLI. Open the repo in VS Code and "Reopen in Container", or create a GitHub Codespace. Dependency install (`vp i`), the Electron exec-bit repair, and the Vite dep-cache warmup all run automatically before you attach.
5 +`.devcontainer/` gives you a ready-to-code Linux environment matching CI: Ubuntu 24.04, Node 26, pnpm, Rust stable, the global `vp` CLI, and the GitHub CLI. Open the repo in VS Code and "Reopen in Container", or create a GitHub Codespace. Dependency install (`vp i`), the Electron exec-bit repair, and the Vite dep-cache warmup all run automatically before you attach.
6
7 ## What works in the container
8
docs/operations/background-verification.md
+1 -1
@@ -1,6 +1,6 @@
1 # Live background-work verification
2
3 -Run from the repository root with Node 24 and installed dependencies. This uses
3 +Run from the repository root with installed dependencies (`vp` provides the pinned Node). This uses
4 real provider CLI credentials and consumes model usage:
5
6 ```sh
docs/operations/development.md
+46 -4
@@ -2,8 +2,8 @@
2
3 ## First checkout
4
5 -Install `vp` using the [root README](../../README.md#install-vp). The checkout requires Node 24;
6 -Bun is optional. From the repository root:
5 +Install `vp` using the [root README](../../README.md#install-vp). It provides the Node version
6 +pinned in `package.json` (Node 26), so no separate Node install is needed. From the repository root:
7
8 ```sh
9 vp i
@@ -15,6 +15,47 @@ a new browser.
15
16 Prefer a container? See [Dev container](../internals/devcontainer.md) for VS Code and Codespaces setup.
17
18 +## GitCafe mirror (optional)
19 +
20 +GitHub is the source of truth. [git.cafe/pingdotgg/t3code](https://git.cafe/pingdotgg/t3code) is a
21 +two-way synced mirror with much higher API rate limits, which helps when many agents read PRs and
22 +issues at once. You never need it to contribute.
23 +
24 +Comments, reviews, labels, and issue edits made on GitCafe sync back to GitHub. The exception is
25 +code: push branches and open PRs on GitHub, where CI runs. GitCafe mirrors a new PR within about a
26 +minute, and from then on you can work with it through either forge.
27 +
28 +```sh
29 +git remote set-url origin https://git.cafe/pingdotgg/t3code.git
30 +git remote add github https://github.com/pingdotgg/t3code.git
31 +# The GitHub remote you push to: `github`, or your fork's remote.
32 +git config remote.pushDefault github
33 +gh repo set-default pingdotgg/t3code
34 +bun install -g @gitcafe/cli # `cafe` needs Bun 1.2 or newer
35 +cafe auth login && cafe auth http setup
36 +cafe skills install --global # optional: cafe-* skills for coding agents
37 +```
38 +
39 +With `origin` on git.cafe:
40 +
41 +- Use `cafe` for existing PRs, issues, comments, reviews, and labels, both reading and writing. Check status
42 + comes from `cafe pr status <n> --json`.
43 +- Create PRs on GitHub: `git push` (to the `pushDefault` remote), then `gh pr create` or `gh stack`.
44 + A PR opened with `cafe pr create` or `cafe stack submit` can get a different number on each forge,
45 + a sync marker appended to its body, and rewritten references, and it cannot come from a fork.
46 +- Write or edit text with closing keywords using `gh`. Any text GitCafe writes to GitHub has its
47 + `#<n>` references turned into GitCafe links, so a `Fixes #<n>` edited through `cafe` silently stops
48 + closing the issue.
49 +- Merge with `gh pr merge <branch> --match-head-commit <sha>`. `cafe pr merge` only pins the head
50 + GitCafe last saw, not the commit you reviewed.
51 +- Use `gh` where the mirror falls short: CI logs and reruns, a fork PR's head repository, and
52 + anything `cafe` returns empty or 403/404 for.
53 +- PR and issue numbers can differ between the forges. Name PRs by branch
54 + (`cafe pr list --head <branch>`, `gh pr view <branch>`), and write `Fixes #<GitHub number>`.
55 +- `cafe` flags differ from `gh`: `--repo` not `-R`, `cafe issue comments <n>` not `--comments`,
56 + `cafe pr status` not `pr checks`. This repository's CI is GitHub Actions on GitHub, so `cafe ci`
57 + has no runs for it; read logs with `gh run view`. `cafe api` paths omit `/api` (`cafe api /repos/...`).
58 +
59 ## Choosing a dev process
60
61 Use `vp run dev` for server and web, or `vp run dev:desktop` for the Electron client.
@@ -27,7 +68,9 @@ Add `--browser` to open a browser automatically.
68 ### State and ports
69
70 Linked worktrees default to their own `.t3/userdata`, even when `T3CODE_HOME` is set.
30 -The main checkout defaults to `~/.t3/dev/userdata`. An explicit `--home-dir` wins in both cases.
71 +The main checkout defaults to `~/.t3/dev`. An explicit `--home-dir` wins in both cases.
72 +The first start in a worktree seeds its empty database from a read-only copy of
73 +`~/.t3/userdata`; `--no-seed` or `T3CODE_DEV_SEED=0` skips that.
74 Never run a development server against the live `~/.t3/userdata`.
75 See [test data](../../AGENTS.md#test-data) for copying a consistent database snapshot.
76
@@ -132,7 +175,6 @@ and runs in headless Chromium with the React Compiler on, like the app. There is
175 TypeScript workspaces typecheck with `tsc`. The `typescript` catalog entry is
176 `@tsc-rs/typescript`, the tsc-rs drop-in, with Effect diagnostics, quick fixes, and
177 refactors built in. VS Code uses it through `js/ts.tsdk.path` in `.vscode/settings.json`.
135 -Marketing keeps `astro check` for Astro files.
178
179 Use `vp run lint:mobile` for native mobile changes. CI owns the full suite; see
180 [ci.yml](../../.github/workflows/ci.yml) for its current jobs.
docs/user/install.md
+1 -1
@@ -48,7 +48,7 @@ Node.js for `npx`).
48 ### Intel Macs
49
50 There is no `t3` executable for Intel Macs (the desktop app is available). To
51 -run a server there, build it from source with Node.js 24 and `vp`
51 +run a server there, build it from source with `vp`, which provides the Node version it needs
52 ([Install vp](https://github.com/pingdotgg/t3code#install-vp)):
53
54 ```bash