Skip to content

docs: document the Windows Terminal ctrl+tab caveat - #57674

Closed
Kissshot-2003 wants to merge 3 commits into
anomalyco:devfrom
Kissshot-2003:windows-terminal-keybinds
Closed

Kissshot-2003 wants to merge 3 commits into
anomalyco:devfrom
Kissshot-2003:windows-terminal-keybinds

Conversation

@Kissshot-2003

@Kissshot-2003 Kissshot-2003 commented Oct 21, 2026 •

Copy link
Copy Markdown

Issue for this PR

Refs #55606

Type of change

  • Bug fix
  • New feature
  • Refactor / code improvement
  • Documentation

What does this PR do?

session.tab.next and session.tab.previous default to ctrl+tab and ctrl+shift+tab. On a default Windows Terminal neither key ever reaches OpenCode, so the advertised default silently does nothing.

The cause is in the terminal, not in the TUI. Windows Terminal binds ctrl+tab and ctrl+shift+tab to its own Terminal.NextTab and Terminal.PrevTab actions, and a terminal key binding consumes the key before the client application sees it.

I measured this on Windows Terminal 1.24.12741 with a probe process that logged every byte the terminal delivered. Same terminal, same run, ctrl+tab / ctrl+shift+tab / tab:

encoding ctrl+tab ctrl+shift+tab tab
default, no unbind (nothing) (nothing) 0x09
ctrl+tab unbound, legacy 0x09 ESC [ Z 0x09
ctrl+tab unbound, kitty requested 0x09 ESC [ Z 0x09
ctrl+tab unbound, win32-input-mode CSI 9 ; 15 ; 0 ; 1 ; 40 ; 1 _ CSI 9 ; 15 ; 0 ; 1 ; 56 ; 1 _ CSI 9 ; 1 ; 9 ; 1 ; 32 ; 1 _

Three things fall out of that:

  • While the terminal holds the binding, the key never arrives at all.
  • Unbinding it is not enough on its own. Windows Terminal ignores the kitty keyboard protocol, so the terminal keeps sending the legacy encoding, where ctrl+tab is the same byte as tab and ctrl+shift+tab is a plain shift+tab. The Ctrl is gone either way.
  • The only encoding that carries the modifier is win32-input-mode, and the win32-input-mode row is the one where the key-down arrives at all.

alt+down and alt+up are not reserved by the terminal and do arrive: they come through as CSI 1 ; 3 B and CSI 1 ; 3 A, which the parser reads as down and up with the alt modifier.

This PR adds a ### Windows Terminal subsection under ## Sessions in services/www/src/docs/content/cli/keybinds.mdx, next to the table that lists the session tab bindings. It says that the terminal reserves ctrl+tab and ctrl+shift+tab, points at alt+down and alt+up as the ones that work, and explains that unbinding the terminal's binding only helps once win32-input-mode is on.

How did you verify your code works?

  • Measured the terminal behaviour rather than inferring it, with a probe process inside Windows Terminal 1.24 that logs every byte the terminal delivers. The comparison that carries the argument is the one in the same run: a key the terminal binds, against one it does not, in each of the three encodings.
  • For the rows that need the terminal's binding released, the probe added { "command": "unbound", "keys": "ctrl+tab" } to the actions array of the terminal's settings.json, took a byte-exact backup first, and restored the file afterwards.
  • Fed the exact bytes Windows Terminal sends for alt+down and alt+up (CSI 1 ; 3 B and CSI 1 ; 3 A) through the TUI's key parser and confirmed they resolve to down and up with the alt modifier set, so the alternative the new subsection points at is one that actually works.
  • Checked the settings.json shape against the Windows Terminal documentation: keybindings was replaced by actions in version 1.4, and "unbound" is the value that releases a default binding.
  • Ran bun typecheck and bun run check:generated from services/www: 0 errors, 0 warnings and 0 hints over the 34 Astro files, and the generated-output check passes.
  • Built the documentation site with bun run build from services/www.

Screenshots / recordings

Not a UI change.

Checklist

  • I have tested my changes locally
  • I have not included unrelated changes in this PR

@github-actions github-actions Bot added the needs:compliance This means the issue will auto-close after 2 hours. label Oct 21, 2026
@github-actions

Copy link
Copy Markdown
Contributor

The following comment was made by an LLM, it may be inaccurate:

@opencode-agent opencode-agent Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

The doc is right about why ctrl+tab/ctrl+shift+tab fail on Windows Terminal and about alt+down/alt+up. I checked the defaults in packages/tui/src/config/keybind.ts and how the TUI sets up the keyboard in packages/tui/src/app.tsx. Nothing to run, since only docs change. Public API is unchanged.

One concern: the second workaround (unbinding the keys in Windows Terminal's settings.json) probably doesn't work today. See the inline comment.

Related: #55606


### Windows Terminal

Windows Terminal binds `ctrl+tab` and `ctrl+shift+tab` to its own tab actions, so those keys never reach OpenCode. Use `alt+down` and `alt+up` to switch session tabs instead, or unbind the terminal's action in `settings.json`:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I don't think the unbind workaround works yet. The TUI only asks for the kitty keyboard protocol (useKittyKeyboard in packages/tui/src/app.tsx) and never asks for win32-input-mode. As your measurements in #55606 show, Windows Terminal ignores the kitty request, so after unbinding, OpenCode still gets the legacy encoding. In that encoding ctrl+tab looks the same as Tab, and ctrl+shift+tab sends no bytes at all. So unbinding probably won't switch session tabs, and ctrl+tab may trigger Tab autocomplete instead. Unless you've tested that unbinding works with the current TUI, I'd drop the settings.json snippet and keep only the alt+down/alt+up advice. Another option is to say the unbind only helps once win32-input-mode is supported (anomalyco/opentui#1726 plus requesting the mode).

@github-actions github-actions Bot removed the needs:compliance This means the issue will auto-close after 2 hours. label Oct 22, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Thanks for updating your PR! It now meets our contributing guidelines. 👍

@opencode-agent opencode-agent Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

My earlier point about the settings.json unbind workaround is fixed: the snippet is gone, and the section now says unbinding isn't enough while win32-input-mode is off, which matches what the TUI asks the terminal for. Nothing else to raise. Docs-only change; public API is unchanged.

Windows Terminal binds ctrl+tab and ctrl+shift+tab to its own tab
actions, so the key-down never reaches the client application. The
session tab bindings list ctrl+tab first, and it silently fails on
the default Windows Terminal.

Measured on Windows Terminal 1.24.12741, a key with no terminal
binding arrives as a full press and release pair, while ctrl+shift+tab
arrives as a release only. alt+down and alt+up are not reserved by the
terminal and arrive as CSI 1 ; 3 B and CSI 1 ; 3 A.

The new subsection sits next to the table that lists the session tab
bindings, points at alt+down and alt+up, and gives the settings.json
snippet that unbinds the terminal's action.

Refs anomalyco#55606
Unbinding ctrl+tab does not help yet: the TUI only requests the kitty
keyboard protocol, which Windows Terminal ignores, and it never turns on
win32-input-mode. After unbinding, the terminal still sends the legacy
encoding, where ctrl+tab is a plain tab and ctrl+shift+tab sends nothing.

Keep the alt+down / alt+up advice, which does work, and state why
unbinding does not.
@Kissshot-2003
Kissshot-2003 force-pushed the windows-terminal-keybinds branch from c799398 to 00a55f2 Compare October 31, 2026 03:49
@Kissshot-2003

Copy link
Copy Markdown
Author

Rebased onto dev and force-pushed (00a55f21). The branch sat on a commit from Oct 21 and had gone CONFLICTING; mergeable is MERGEABLE again.

The conflict was in services/www/src/docs/content/cli/keybinds.mdx. In the ~1100 commits since, the section heading was changed from ## Models And Agents to ## Models and agents (sentence case), and this PR inserts a ### Windows Terminal block immediately before it. Resolved by keeping the new section and adopting the upstream heading casing, so the diff is what it was meant to be: one section, +6 lines, nothing else. The two follow-up commits (dropping the unbind workaround, describing what the legacy encoding actually delivers) applied cleanly on top.

One thing worth knowing: the required checks on dev (typecheck, unit (linux/windows), e2e (linux/windows), bot-scope) have never reported on this branch — every pull_request run here is action_required, i.e. waiting for a maintainer to approve the workflow, because this is my first PR to this repo. Only the pull_request_target checks (check-compliance, check-standards) ran, and both pass. Approving the run is all that's needed to see the rest.

@Kissshot-2003

Copy link
Copy Markdown
Author

Superseded by the docs-tree move: #63117 removed packages/web and services/www, and the V1 docs now live under services/site/src/docs/v1/content/, so this branch no longer applies (CONFLICTING).

The Windows Terminal ctrl+tab caveat is still absent from the new services/site/src/docs/v1/content/keybinds.mdx — the content is worth re-landing on the new path.

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.

1 participant