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 22, 19:30 UTC
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