The best way to control Claude Code, Codex and more from any computer or phone
docs: open and track PRs through GitCafe when origin is git.cafe (#25126)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Julius Marminge committed
Oct 25, 2026 at 16:27 UTC
3ddfcfc44ebb1f03358d38d0a1c057fed6ae981e
2 files changed
+19
-27
AGENTS.md
+1
-1
@@ -139,7 +139,7 @@ For authorized mobile verification, a missing or outdated native client is an in
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.
142
+- If `origin` is git.cafe, follow [GitCafe mirror](docs/operations/development.md#gitcafe-mirror-optional): push to `origin`, open and track PRs with `cafe` and their git.cafe URLs, and keep `gh` for CI logs and merging.
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/operations/development.md
+18
-26
@@ -18,43 +18,35 @@ Prefer a container? See [Dev container](../internals/devcontainer.md) for VS Cod
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.
21
+two-way synced mirror with much higher API rate limits, which helps when many agents work at once.
22
+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.
24
+Pushes, PRs, comments, reviews, labels, and issue edits made on GitCafe sync to GitHub within
25
+about a minute, and PR and issue numbers match. CI runs on GitHub, and its checks show up on
26
+GitCafe.
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
31
+gh repo set-default pingdotgg/t3code # for the few `gh` commands below
32
bun install -g @gitcafe/cli # `cafe` needs Bun 1.2 or newer
33
cafe auth login && cafe auth http setup
34
cafe skills install --global # optional: cafe-* skills for coding agents
35
```
36
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>`.
37
+With `origin` on git.cafe, work through GitCafe and leave GitHub's API alone:
38
+
39
+- Push to `origin`, open PRs with `cafe pr create` (`--head owner/repo:branch` from a fork) or
40
+ `cafe stack submit`, and use `cafe` for everything after that. Link the git.cafe PR URL, not the
41
+ github.com one, wherever a tool tracks the PR, so polling stays on GitCafe.
42
+- Read checks with `cafe pr status <n>`.
43
+- Write closing references as `Fixes pingdotgg/t3code#<n>`. GitCafe turns a bare `#<n>` in text it
44
+ syncs to GitHub into a git.cafe link, and GitHub does not close issues from those.
45
+- Two things still need `gh`: CI logs and reruns (`gh run view --log`, `gh run rerun`), and
46
+ merging, with `gh pr merge <n> --match-head-commit <sha>`, because `cafe pr merge` cannot pin
47
+ the commit you reviewed.
48
- `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/...`).
49
+ `cafe pr status` not `pr checks`. `cafe api` paths omit `/api` (`cafe api /repos/...`).
50
51
## Choosing a dev process
52