Skip to content

Use C-Space tmux prefix in remote sessions; document GitHub stacked PRs for agents #28

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Vilos92 merged 4 commits into from
Aug 4, 2026
Merged

Use C-Space tmux prefix in remote sessions; document GitHub stacked PRs for agents #28

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b6eaf31
:sparkles: Use C-Space tmux prefix in ssh/mosh sessions
Vilos92 Aug 4, 2026
f517a9a
:memo: Always use native GitHub stacked PRs for branch chains
Vilos92 Aug 4, 2026
cc2a40f
:wrench: Turn off CodeRabbit auto-reviews
Vilos92 Aug 4, 2026
aa93677
:memo: Correct gh-stack prerequisites, link semantics, and sync pruning
Vilos92 Aug 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 1 addition & 4 deletions .coderabbit.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,7 @@ reviews:
review_status: true
review_details: false
auto_review:
# Unlike scriptlancer, dotfiles keeps automatic reviews on — CodeRabbit
# already reviews every PR here and that behavior should survive adopting
# this config.
enabled: true
enabled: false
drafts: false
chat:
auto_reply: true
36 changes: 36 additions & 0 deletions claude-md/.claude/CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,6 +122,42 @@ Don't ask for trivial one-offs, quick lookups, or single-file edits.

---

## GitHub stacked PRs (use the native feature)

**The rule:** whenever work forms a chain of dependent branches — branch A targeting `main`, branch B targeting A, C targeting B — **always use GitHub's native stacked pull requests**, never ad-hoc chained PRs or manual base-branch juggling. The trigger is simple: if you're about to open a PR whose base is another open PR's branch, make it a native stack instead. Independent changes are not a stack — keep those as separate PRs against `main`.

@coderabbitai coderabbitai Bot Aug 4, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

sed -n '115,165p' claude-md/.claude/CLAUDE.md

Repository: Vilos92/dotfiles

Length of output: 5678

🌐 Web query:

GitHub gh-stack native stacked pull requests private preview same repository cross-fork support

💡 Result:

As of August 4, 2026, GitHub's native stacked pull request functionality is in public preview [1][2][3]. The feature allows users to chain pull requests within the same repository, where each pull request targets the branch of the one below it [1][4]. Key details regarding the current status and limitations of this feature: 1. Repository Requirement: Stacked pull requests must reside entirely within the same repository [1][3]. Official GitHub documentation explicitly states that cross-fork stacks are not supported [1][3]. 2. Public Preview Status: The feature transitioned from private preview to public preview on July 30, 2026 [2][5]. 3. Tooling Support: Management of these stacks is primarily handled through the gh stack GitHub CLI extension [1][3][6]. The feature is also integrated into the GitHub website, GitHub Mobile, and is accessible via the API, allowing users to navigate and merge stacked pull requests directly within the platform [3][4]. Because the requirement for all branches to be in the same repository is a stated limitation in the official documentation, cross-fork support remains unavailable at this time [1][3].

Citations:

Make native stacks conditional on support.

If gh-stack is unavailable or the branches span repositories, use the documented manual fallback. Native stacked PRs currently require all branches to be in the same repository. Update the rule and lines 153–157 accordingly.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@claude-md/.claude/CLAUDE.md` at line 127, Update the stacked pull request
rule to use GitHub native stacks only when gh-stack is available and all
branches are in the same repository. Revise the guidance around the manual
workflow to document using manual base-branch management when gh-stack is
unavailable or repositories differ, while preserving separate PRs against main
for independent changes.


**Tooling:** the official `gh-stack` extension (requires GitHub CLI v2.0+):

```sh
gh extension install github/gh-stack # one-time setup
gh skill install github/gh-stack # agent skill: install when doing heavy stack work
```

**Core workflow:**

```sh
gh stack init # start a stack; names the bottom branch
gh stack add <branch> # new branch on top of the current layer (-Am "msg" stages + commits too)
gh stack submit # push all branches and create/update PRs with correct bases + stack link
gh stack view # branches, PR links, statuses across the stack
gh stack sync # fetch, cascading rebase, push, sync PR state — one command
gh stack merge # merge one or multiple layers
gh stack link # adopt existing branches/PR chains into a native stack
```

**Semantics to respect (don't fight them manually):**

- Stacks merge **bottom-to-top**. Merging a mid-stack PR also merges everything below it in one operation. The PRs above stay open, **auto-retarget** to the trunk, and GitHub **automatically rebases** the next unmerged PR server-side — never hand-edit the base branch of a stacked PR. Your **local** branches don't follow along, though: run `gh stack sync` after a merge to pull down the rewritten branches — with `--prune` to delete local branches for merged PRs, since the default prompts interactively.
- **Other drift is NOT auto-rebased.** If the trunk moves ahead or you push changes to a lower layer, the stack goes non-linear and merging is blocked until you explicitly rebase: the **Rebase stack** button in the merge box (server-side), or locally `gh stack rebase --upstack` after amending a lower layer / `gh stack rebase` for trunk drift. Don't hand-`git rebase` each branch in the chain.
- Branch protection and CI requirements come from the **bottom PR's base branch** and apply to every layer.
- Public-preview limits: all branches must live in the **same repository** (no cross-fork stacks), and programmatic merges must go through `gh stack merge` / the new merge API — not the classic merge endpoint.

**Adopting an existing chain:** if a traditional stack already exists (PRs manually chained by base branch), `gh stack link` creates or updates the stack on GitHub from branch names or PR numbers — remote linking only; it stores no local tracking state. To also manage the chain locally (`rebase`, `sync`), set up tracking with `gh stack init` / `gh stack checkout`.

**Fallback:** if `gh-stack` truly isn't available (old `gh`, extensions blocked), note that briefly, then fall back to manually chained PRs with explicit bases and a "depends on #N" note in each PR description — but treat this as the exception, not a preference.

---

## Checking Woodpecker CI failures (greg-zone)

Greg's personal repos — those under the **`Vilos92`** GitHub user (e.g. `Vilos92/dotfiles`, `Vilos92/scriptlancer`) — run CI on a self-hosted **Woodpecker** instance at **`http://greg-zone:9011`** (Tailscale-only). GitHub shows a single status per pipeline (e.g. **`ci/woodpecker/pr/woodpecker`**) with **no logs behind it**—the per-step results and logs live in Woodpecker. When a PR's Woodpecker check fails, fetch the failure yourself instead of asking for a paste.
Expand Down
8 changes: 8 additions & 0 deletions tmux/.tmux.conf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,11 @@
# Remote (ssh/mosh) sessions use C-Space as prefix, so the local C-b doesn't
# need doubling to reach nested tmux; mosh sets SSH_CONNECTION but not SSH_TTY
if-shell 'test -n "$SSH_CONNECTION" || test -n "$SSH_TTY"' {
unbind C-b
set -g prefix C-Space
bind C-Space send-prefix
}
Comment on lines +3 to +7

@coderabbitai coderabbitai Bot Aug 4, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift

🧩 Analysis chain

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

socket="coderabbit-prefix-review-$$"
trap 'tmux -L "$socket" kill-server >/dev/null 2>&1 || true' EXIT

env -u SSH_CONNECTION -u SSH_TTY \
  tmux -L "$socket" -f tmux/.tmux.conf \
  new-session -d -s persistent

before="$(tmux -L "$socket" show-options -gv prefix)"

SSH_CONNECTION='client 1 2 3' \
  tmux -L "$socket" new-session -d -s ssh-client

after="$(tmux -L "$socket" show-options -gv prefix)"

test "$before" = C-b
test "$after" = C-Space

Repository: Vilos92/dotfiles

Length of output: 197

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

printf '%s\n' '--- tmux/.tmux.conf ---'
cat -n tmux/.tmux.conf

printf '%s\n' '--- relevant AGENTS.md text ---'
if [ -f AGENTS.md ]; then
  sed -n '75,95p' AGENTS.md
else
  printf '%s\n' 'AGENTS.md not found at repository root'
fi

printf '%s\n' '--- tmux references ---'
rg -n -i 'tmux|C-Space|C-b|SSH_CONNECTION|SSH_TTY' --glob '!node_modules' --glob '!dist' --glob '!build' .

Repository: Vilos92/dotfiles

Length of output: 5630

🌐 Web query:

tmux man page server reads configuration when server starts new client attaches environment SSH_CONNECTION

💡 Result:

The tmux server reads its configuration files only when it first starts [1]. By default, it loads /etc/tmux.conf if present, followed by the user configuration file at ~/.tmux.conf or the location specified by $XDG_CONFIG_HOME/tmux/tmux.conf [2][3][1]. Regarding the interaction between tmux and environment variables like SSH_CONNECTION when a client attaches, the following points apply: 1. Server Lifecycle: The tmux server is a long-running process [4]. Once started, it does not re-read configuration files or refresh its global environment unless explicitly instructed to do so (e.g., via the source-file command) [5][1]. 2. update-environment Option: tmux maintains a session environment that is merged with the global environment when new windows are created [6][7]. To ensure that specific environment variables—such as SSH_CONNECTION or SSH_AUTH_SOCK—are updated in the session when a client attaches to an existing server, those variables must be included in the tmux option update-environment [7][8]. 3. Client Attachment: When update-environment is configured, tmux automatically updates the variables listed in that option within the session environment whenever a new client attaches [7]. This allows the new client's environment values to be propagated to the session [9][7]. 4. Existing Processes: Note that updating environment variables in the tmux session environment affects only new windows or panes created after the update [7]. Existing shell processes already running within the tmux session will typically retain their original, stale environment variables unless the user manually updates them, for example by using tmux show-environment to export the new values into the current shell [9][7].

Citations:

Use separate tmux sockets for local and SSH clients. if-shell runs when the tmux server reads its configuration, not when a client attaches. An existing server therefore keeps the prefix selected by its startup environment, which can break the documented prefix + d detach workflow. Add lifecycle coverage for this case.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tmux/.tmux.conf` around lines 3 - 7, Update the tmux configuration around the
SSH-based prefix selection so local and SSH clients use separate tmux sockets,
rather than relying on if-shell evaluation during server startup. Ensure each
socket applies the correct prefix for its client type and preserves the
documented prefix-plus-d detach workflow, and add lifecycle coverage verifying
behavior when clients attach to an existing server.


# Address vim mode switching delay
set -sg escape-time 0

Expand Down