| name | keybinding-maintenance |
| description | When updating keybinding hints, mode names, or keybindings themselves, this skill ensures all related files are updated consistently and become effective. Activates when working on keybindings, hints, or related configuration changes. |
| version | 1.0.0 |
Keybinding Maintenance Skill
When modifying keybindings, hint texts, or mode-related configuration, changes must be applied consistently across multiple files to take effect. This skill identifies all locations that must be updated.
When This Skill Applies
Activate when:
- Adding, removing, or renaming keybindings
- Changing hint text labels (e.g., "zoom" → "focus")
- Modifying mode names or descriptions
- Updating keybinding descriptions or comments
- Any change to
Ctrl+* or mode activation keys
Critical File Locations for Keybinding Changes
1. Keybinding Definitions (Active - keybindings work)
File: tmux/keybindings.conf
What to update:
- Key binding commands:
bind -T pane f ...
- Comments describing each binding
- Mode names in key table switches
Example:
# ❌ Old: Toggle fullscreen
# ✅ New: Toggle fullscreen (focus pane)
bind -T pane f resize-pane -Z \; switch-client -T root
2. Status Bar Hints - Hardcoded (CRITICAL - What users see)
File: tmux/statusbar.conf
What to update:
- Pane mode hint in
if-shell conditions (appears twice for WSL and Linux)
- Tab mode hints
- Session mode hints
- Move/Resize/Git mode hints
- Root mode keybinding legend
Example:
# ❌ Old: #[fg=colour81]f#[default]: zoom
# ✅ New: #[fg=colour81]f#[default]: focus
# Both if-shell branches MUST be updated:
"set -g status-right '...#{?#{==:#{client_key_table},pane},...
[...n: new | d: below | r: right | f: focus | x: kill | ←↑↓→: nav...]
..."
Critical: Status bar hints appear twice in statusbar.conf:
- Inside first
if-shell (WSL detection)
- Inside second
if-shell (Linux/macOS)
Both must match - updating only one leaves inconsistency.
3. Helper Script Hints (Backup/Reference)
File: scripts/get-mode-help.sh
What to update:
- Case statements for each mode (pane, tab, session, move, resize, git)
- Echo output containing hint text
Example:
pane)
echo "#[fg=colour244][...f#[default]: focus...]"
;;
Note: This script is NOT currently used by the status bar (hints are hardcoded in statusbar.conf), but it serves as documentation and could be called in the future via the statusbar. Keep it in sync with statusbar.conf for consistency.
4. Documentation (Optional but recommended)
Files:
docs/keymap.md - User-facing keybinding reference tableREADME.md - Feature descriptions- Commit messages - Describe what changed
Example in docs/keymap.md:
| `f` | Toggle focus (fullscreen) |
Exact Locations Checklist
Use this checklist when updating any keybinding or hint:
For hint text changes (e.g., "zoom" → "focus"):
For new keybindings (e.g., adding Ctrl+g for git):
For removing keybindings:
Why Multiple Locations?
- statusbar.conf (hardcoded) - Direct status bar output; actual source of truth for what displays
- get-mode-help.sh - Extracted hints; serves as documentation and fallback/future use
- keybindings.conf - Binding logic; comments help developers understand intent
- docs/keymap.md - User-facing documentation; must match implementation
Verification Steps
After making keybinding changes:
- Syntax check:
tmux -f ~/.config/tmux/tmux.conf -S
- Reload config: In tmux, press
Ctrl+a, then r
- Test hints: Press the keybinding mode key (e.g.,
Ctrl+p) and check status bar
- Verify all files: Search for old text to ensure no instances remain
grep -r "zoom" --include="*.conf" --include="*.sh" --include="*.md"
Common Mistakes to Avoid
❌ Updating only get-mode-help.sh - Changes won't appear in status bar (not currently used)
✅ Update statusbar.conf - The actual source for status bar display
❌ Updating only one if-shell branch in statusbar.conf - WSL users won't see changes
✅ Update both if-shell blocks - Ensure consistency across platforms
❌ Forgetting documentation - Users don't know about the new keybinding
✅ Update docs/keymap.md - Keep user docs in sync
CRITICAL: Dynamic Width Conditionals in statusbar.conf
The two set -g status-right lines in statusbar.conf are extremely long (500+ chars each). Every edit carries the risk of accidentally truncating the dynamic width conditionals at the tail of each line:
#{?#{e|>=|:#{client_width},220}, 🔋 <battery widget>,}#{?#{e|>=|:#{client_width},190}, ⏰ %H:%M 📅 %d %b %Y,}
These conditionals hide the battery widget below 220 columns and the time/date below 190 columns. If they are dropped the widgets are always visible and break narrow terminal layouts. This happened once already (fixed in commit 91679fa).
Safe editing rule
Only replace the minimum substring that must change. Never replace large swaths of the line. For example, to rename a hint from Ctrl+u to Ctrl+a U, replace only the literal string Ctrl+u, not the surrounding 200+ characters.
Mandatory post-edit verification
After any edit to tmux/statusbar.conf, run:
grep -o 'client_width' tmux/statusbar.conf | wc -l
Expected output: 4 (two conditionals × two if-shell branches). If the count is less than 4, the edit dropped a conditional and must be fixed before committing.
Implementation Pattern
When making a keybinding hint change, follow this order:
- Update
tmux/statusbar.conf (both if-shell branches)
- Update
tmux/keybindings.conf comments
- Update
scripts/get-mode-help.sh for documentation
- Update
docs/keymap.md for users
- Reload and test: Enter the mode and check status bar
- Verify with grep that no old text remains
Key Insight
The status bar displays hardcoded hints, not dynamic script output. All hint changes must be made in statusbar.conf to be effective. The get-mode-help.sh script exists for testing, documentation, and potential future use if the architecture changes to call the script.
Files Modified by This Skill Knowledge
tmux/
├── keybindings.conf ← Binding definitions + comments
├── statusbar.conf ← CRITICAL: Status bar hints (two if-shell blocks)
└── modes/
├── pane.conf
├── tab.conf
├── resize.conf
└── move.conf
scripts/
└── get-mode-help.sh ← Hint documentation (not currently used)
docs/
└── keymap.md ← User-facing reference
.claude/skills/
└── keybinding-maintenance/
└── SKILL.md ← This file
