Skip to content

feat: jump to session via terminal adapter registry (cmux/tmux/iTerm2)#138

Open
Valgard wants to merge 1 commit into
graykode:mainfrom
Valgard:feat/terminal-jump-adapters
Open

feat: jump to session via terminal adapter registry (cmux/tmux/iTerm2)#138
Valgard wants to merge 1 commit into
graykode:mainfrom
Valgard:feat/terminal-jump-adapters

Conversation

@Valgard

@Valgard Valgard commented Jun 11, 2026

Copy link
Copy Markdown

What

Enter "jump to session" worked only inside tmux. This refactors the inline tmux logic into a TerminalJumper registry under src/jump/ (one adapter per file) and adds two backends:

  • cmux — read CMUX_WORKSPACE_ID from the agent process env, then cmux select-workspace --workspace <uuid>.
  • iTerm2 — match the process's controlling tty to an iTerm2 session and focus it via AppleScript (select pane/tab/window + activate).
  • tmux — existing behavior preserved (now an adapter; "PID not in any pane" became NotApplicable so other backends can try).

How

resolve() walks jumpers() in order (cmux → tmux → iTerm2). The three-way JumpAttempt (NotApplicable / Jumped / Failed) makes adapters composable — first applicable wins, NotApplicable falls through. Backends are mutually exclusive by controlling tty.

Tests / verification

  • 15 new unit tests for the registry loop and the parsing helpers.
  • Live-tested on macOS / iTerm2 — focus lands on the correct pane/tab/window.
  • Full CI gate green locally on rustc 1.96.0: cargo clippy -- -D warnings, cargo test (180 passed), cargo build --release.

Notes

  • iTerm2's first jump triggers a one-time macOS Automation permission prompt; until granted it surfaces as a status message, not a crash.
  • Docs updated in AGENTS.md (Key Bindings + new "Terminal Jump" section).

Closes #137

Enter previously jumped to a session only inside tmux. Replace the inline
tmux logic with a TerminalJumper registry (src/jump/, one adapter per file):

- cmux:   read CMUX_WORKSPACE_ID from the agent process env, then
          `cmux select-workspace --workspace <uuid>`
- tmux:   the existing pane-switch, refactored; "PID not in any pane" is now
          NotApplicable so other backends can try
- iTerm2: match the process's controlling tty to an iTerm2 session and focus
          it via AppleScript (select pane/tab/window + activate)

resolve() walks jumpers() in order; the three-way JumpAttempt
(NotApplicable/Jumped/Failed) makes the adapters composable. Parsing and the
registry loop are unit-tested (15 new tests).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Jump to session beyond tmux (iTerm2, cmux) via terminal adapter registry

1 participant