fix(terminal): resolve Ctrl+B keybinding conflict between Zellij and Claude Code

[ncrmro]

fix(terminal): resolve Ctrl+B keybinding conflict between Zellij and Claude Code

Zellij's default Ctrl+B (enter Tmux mode) intercepts Claude Code's Ctrl+B (background running tasks), making it impossible to background tasks from inside a Zellij session. This is the same class of conflict already resolved for Ctrl+G and Ctrl+O in shell.nix.

Additionally, there is no single reference table documenting which Ctrl-key bindings are claimed by Zellij vs Claude Code vs other terminal tools, making future conflicts harder to spot.

User stories

• As a developer using Claude Code inside Zellij, I want Ctrl+B to background Claude tasks so that Zellij does not steal the keypress.
• As a keystone contributor editing shell.nix, I want a cross-reference table of all Ctrl-key bindings so that I can avoid introducing new conflicts.

Architecture

Terminal input (Ghostty/Kitty)
  │
  ▼
┌─────────────────────────────────────────────┐
│ Zellij (outer multiplexer)                  │
│  normal mode keybinds:                      │
│    Ctrl+B → Tmux mode  ← CONFLICT          │
│    Ctrl+G → (unbound, was Lock mode)        │
│    Ctrl+O → (unbound, was Session mode)     │
│    Ctrl+T → new tab prompt                  │
│    Ctrl+W → close tab                       │
│    Ctrl+, / Ctrl+. → prev/next tab          │
└────────────┬────────────────────────────────┘
             │ (passthrough)
             ▼
┌─────────────────────────────────────────────┐
│ Claude Code (inner application)             │
│    Ctrl+B → background tasks  ← BLOCKED    │
│    Ctrl+G → open in editor                  │
│    Ctrl+O → toggle transcript               │
│    Ctrl+T → toggle task list                │
│    Ctrl+R → reverse search history          │
│    Ctrl+L → clear prompt                    │
└─────────────────────────────────────────────┘

Affected modules

• modules/terminal/shell.nix — Zellij keybind configuration (add unbind "Ctrl b")
• modules/terminal/AGENTS.md — add cross-reference keybinding table

Requirements

Zellij unbind

ISSUE-REQ-1 Zellij MUST unbind Ctrl+B in normal mode so the keypress passes through to inner applications.

ISSUE-REQ-2 If Zellij Tmux mode functionality is still desired, it SHOULD be rebound to Ctrl+Shift+B (consistent with the Ctrl+Shift pattern used for Ctrl+G → Ctrl+Shift+G and Ctrl+O → Ctrl+Shift+O).

ISSUE-REQ-3 Zellij SHOULD also unbind Ctrl+B in scroll and search modes (where it defaults to PageScrollUp) to avoid mode-specific conflicts.

Documentation

ISSUE-REQ-4 modules/terminal/AGENTS.md MUST include a Ctrl-key cross-reference table showing which tool claims each binding and any remaps.

ISSUE-REQ-5 Each unbind in shell.nix MUST have a comment naming the conflicting tool (already the case for Ctrl+G and Ctrl+O — extend the pattern).

Validation

ISSUE-REQ-6 After ks build, the rendered Zellij config (~/.config/zellij/config.kdl) MUST NOT contain bind "Ctrl b" in any mode.

Deliverables

• Unbind Ctrl+B in Zellij normal mode (shell.nix)
• Rebind Tmux mode to Ctrl+Shift+B (shell.nix)
• Add keybinding cross-reference table to modules/terminal/AGENTS.md
• Verify with ks build that rendered config is correct

Acceptance criteria

• Ctrl+B inside Claude Code in Zellij backgrounds tasks correctly
• Zellij Tmux mode is still accessible via Ctrl+Shift+B
• AGENTS.md documents all Ctrl-key assignments across Zellij, Claude Code, and other tools
• nix flake check --no-build passes

Issue metadata

• Repository: ncrmro/keystone
• Suggested labels: bug

[ncrmro]

Closing as part of PM bankruptcy (2026-07): pre-v1 backlog reset. Only M9 (v1 — Stabilization) stays open; reopen if this blocks v1.