Add crew tmux configuration documentation

Explains how to set up personal tmux config for quick cycling between crew sessions using hardwired C-b n/p keybindings.
2025-12-25 19:27:41 -08:00
parent e3d33770c6
commit 619ff02aa7
1 changed files with 156 additions and 0 deletions
--- a/docs/crew-tmux-config.md
+++ b/docs/crew-tmux-config.md
@@ -0,0 +1,156 @@
+# Crew tmux Configuration
+
+> **Status**: Personal Workflow
+> **Location**: Your personal dotfiles (e.g., `~/.emacs.d/tmux.conf`)
+
+## Overview
+
+Crew workers are persistent identities. Unlike polecats (ephemeral, witness-managed),
+crew members keep their names and workspaces across sessions. This makes them ideal
+candidates for hardwired tmux keybindings.
+
+This document explains how to configure your personal tmux config to enable quick
+cycling between crew sessions within a rig.
+
+## Why Personal Config?
+
+Crew session linking is **personal workflow**, not core Gas Town infrastructure:
+
+- Your crew members are stable identities you control
+- The groupings reflect how *you* want to work
+- Different users may have different crew setups
+- Keeps Gas Town codebase focused on agent mechanics
+
+Store this in your personal dotfiles repo (e.g., `~/.emacs.d/`) for:
+- Version control
+- Sharing across machines
+- Separation from project code
+
+## Setup
+
+### 1. Create tmux.conf in your dotfiles
+
+```bash
+# Example: ~/.emacs.d/tmux.conf
+```
+
+### 2. Symlink from home
+
+```bash
+ln -s ~/.emacs.d/tmux.conf ~/.tmux.conf
+```
+
+### 3. Configure crew cycling groups
+
+The key insight: use `run-shell` with a case statement to route `C-b n`/`C-b p`
+based on the current session name.
+
+```tmux
+# Crew session cycling - hardwired groups
+# Group 1: gastown crew (max <-> joe)
+# Group 2: beads crew (dave -> emma -> zoey -> dave)
+
+bind n run-shell ' \
+  s="#{session_name}"; \
+  case "$s" in \
+    gt-gastown-crew-max) tmux switch-client -t gt-gastown-crew-joe ;; \
+    gt-gastown-crew-joe) tmux switch-client -t gt-gastown-crew-max ;; \
+    gt-beads-crew-dave) tmux switch-client -t gt-beads-crew-emma ;; \
+    gt-beads-crew-emma) tmux switch-client -t gt-beads-crew-zoey ;; \
+    gt-beads-crew-zoey) tmux switch-client -t gt-beads-crew-dave ;; \
+    *) tmux switch-client -n ;; \
+  esac'
+
+bind p run-shell ' \
+  s="#{session_name}"; \
+  case "$s" in \
+    gt-gastown-crew-max) tmux switch-client -t gt-gastown-crew-joe ;; \
+    gt-gastown-crew-joe) tmux switch-client -t gt-gastown-crew-max ;; \
+    gt-beads-crew-dave) tmux switch-client -t gt-beads-crew-zoey ;; \
+    gt-beads-crew-emma) tmux switch-client -t gt-beads-crew-dave ;; \
+    gt-beads-crew-zoey) tmux switch-client -t gt-beads-crew-emma ;; \
+    *) tmux switch-client -p ;; \
+  esac'
+```
+
+### 4. Reload config
+
+```bash
+tmux source-file ~/.tmux.conf
+```
+
+## Session Naming Convention
+
+Gas Town uses predictable session names:
+
+```
+gt-<rig>-crew-<name>
+```
+
+Examples:
+- `gt-gastown-crew-max`
+- `gt-gastown-crew-joe`
+- `gt-beads-crew-dave`
+- `gt-beads-crew-emma`
+- `gt-beads-crew-zoey`
+
+This predictability enables hardwired keybindings.
+
+## Adding New Crew Members
+
+When you add a new crew member:
+
+1. Add entries to both `bind n` and `bind p` case statements
+2. Maintain the cycle order (n goes forward, p goes backward)
+3. Reload config: `tmux source-file ~/.tmux.conf`
+
+Example - adding `frank` to gastown crew:
+
+```tmux
+# In bind n:
+gt-gastown-crew-max) tmux switch-client -t gt-gastown-crew-joe ;;
+gt-gastown-crew-joe) tmux switch-client -t gt-gastown-crew-frank ;;
+gt-gastown-crew-frank) tmux switch-client -t gt-gastown-crew-max ;;
+
+# In bind p (reverse order):
+gt-gastown-crew-max) tmux switch-client -t gt-gastown-crew-frank ;;
+gt-gastown-crew-joe) tmux switch-client -t gt-gastown-crew-max ;;
+gt-gastown-crew-frank) tmux switch-client -t gt-gastown-crew-joe ;;
+```
+
+## Fallback Behavior
+
+The `*) tmux switch-client -n ;;` fallback means:
+- In a crew session → cycles within your group
+- In any other session (mayor, witness, refinery) → standard all-session cycling
+
+This keeps the default behavior for non-crew contexts.
+
+## Starting Crew Sessions
+
+When starting crew sessions manually (not through Gas Town spawn), remember to
+configure the status line:
+
+```bash
+# Start session
+tmux new-session -d -s gt-<rig>-crew-<name> -c /path/to/crew/<name>
+
+# Configure status (Gas Town normally does this automatically)
+tmux set-option -t gt-<rig>-crew-<name> status-left-length 25
+tmux set-option -t gt-<rig>-crew-<name> status-left "👷 <rig>/crew/<name> "
+
+# Start Claude
+tmux send-keys -t gt-<rig>-crew-<name> 'claude' Enter
+```
+
+## Tips
+
+- **Two-member groups**: For pairs like max/joe, n and p do the same thing (toggle)
+- **Larger groups**: n cycles forward, p cycles backward
+- **Mixed rigs**: Each rig's crew is a separate group - no cross-rig cycling
+- **Testing**: Use `tmux display-message -p '#{session_name}'` to verify session names
+
+## Related
+
+- [session-lifecycle.md](session-lifecycle.md) - How sessions cycle
+- [propulsion-principle.md](propulsion-principle.md) - The "RUN IT" protocol