Skip to content

Commit 52c2b38

Browse files
docs: document the GitCafe mirror and refresh the dev setup (#23808)
Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent 22840ab commit 52c2b38

6 files changed

Lines changed: 52 additions & 9 deletions

File tree

‎.devcontainer/devcontainer.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -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)
22
// and the canonical setup in docs/operations/development.md: global `vp`, `vp i`.
33
// Contributor doc: docs/internals/devcontainer.md
44
{
@@ -8,7 +8,7 @@
88
// nodeGypDependencies (default true) brings python3/make/g++, which Linux
99
// needs for node-pty's node-gyp fallback (its prebuilds are mac/win only).
1010
"ghcr.io/devcontainers/features/node:2": {
11-
"version": "24"
11+
"version": "26"
1212
},
1313
// native/resource-monitor (edition 2024, needs stable >= 1.85). The server
1414
// degrades gracefully without the binary, but CI checks cargo fmt + test.

‎AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,7 @@ For authorized mobile verification, a missing or outdated native client is a bui
139139
## Pull requests
140140

141141
- 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.
142143
- Conventional commit titles, plain language: `fix(web): new threads no longer spike CPU`.
143144
- Body: the problem in a sentence or two, then how you fixed it. End with the model and harness that did the work.
144145
- UI changes need before/after images. Motion or timing needs a short video.

‎docs/internals/devcontainer.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
> For maintainers. Using T3 Code? See [docs/user](../user/).
44
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.
66

77
## What works in the container
88

‎docs/operations/background-verification.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Live background-work verification
22

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
44
real provider CLI credentials and consumes model usage:
55

66
```sh

‎docs/operations/development.md‎

Lines changed: 46 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22

33
## First checkout
44

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:
77

88
```sh
99
vp i
@@ -15,6 +15,47 @@ a new browser.
1515

1616
Prefer a container? See [Dev container](../internals/devcontainer.md) for VS Code and Codespaces setup.
1717

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+
1859
## Choosing a dev process
1960

2061
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.
2768
### State and ports
2869

2970
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.
3174
Never run a development server against the live `~/.t3/userdata`.
3275
See [test data](../../AGENTS.md#test-data) for copying a consistent database snapshot.
3376

@@ -132,7 +175,6 @@ and runs in headless Chromium with the React Compiler on, like the app. There is
132175
TypeScript workspaces typecheck with `tsc`. The `typescript` catalog entry is
133176
`@tsc-rs/typescript`, the tsc-rs drop-in, with Effect diagnostics, quick fixes, and
134177
refactors built in. VS Code uses it through `js/ts.tsdk.path` in `.vscode/settings.json`.
135-
Marketing keeps `astro check` for Astro files.
136178

137179
Use `vp run lint:mobile` for native mobile changes. CI owns the full suite; see
138180
[ci.yml](../../.github/workflows/ci.yml) for its current jobs.

‎docs/user/install.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ Node.js for `npx`).
4848
### Intel Macs
4949

5050
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
5252
([Install vp](https://github.com/pingdotgg/t3code#install-vp)):
5353

5454
```bash

0 commit comments

Comments
 (0)