starred/terminal
1
0
Fork 0
mirror of https://github.com/microsoft/terminal.git synced 2026-07-08 18:16:28 +00:00
Code Issues 19.0k Packages Projects Releases 20 Wiki Activity

[PR #19784] Add --session option to focus-tab command #31958

New Issue
Open
opened 2026-01-31 09:50:37 +00:00 by claunia · 0 comments
claunia commented 2026-01-31 09:50:37 +00:00
Owner
Copy Link

Original Pull Request: https://github.com/microsoft/terminal/pull/19784

State: closed
Merged: No

Summary of the Pull Request

Adds a --session / -s option to the wt focus-tab command that accepts a WT_SESSION GUID. This allows external processes to programmatically focus the exact terminal tab and pane where a specific shell session is running.

Primary use case: AI coding agents (GitHub Copilot CLI, Claude Code, Cursor, Aider, etc.) run long-running tasks in terminal sessions. When the task completes, users have often alt-tabbed away and opened many other tabs. This feature lets agents bring users back to the correct tab automatically:

# Agent saves session at startup
$mySession = $env:WT_SESSION

# ... long task runs, user alt-tabs away ...

# Agent brings user back to the right place
wt focus-tab --session $mySession

References and Relevant Issues

Detailed Description of the Pull Request / Additional comments

Usage

wt focus-tab --session $env:WT_SESSION
wt ft -s $env:WT_SESSION

What it does

  1. Finds the tab containing the pane with the matching WT_SESSION GUID
  2. Switches to that tab (routing to the correct window on the current desktop)
  3. Focuses the specific pane if the tab has split panes

Implementation

File Change
AppCommandlineArgs.cpp Added --session/-s option with GUID parsing. Auto-sets -w 0. Updated ValidateStartupCommands().
AppCommandlineArgs.h Added _focusTabSession member
ActionArgs.idl Extended SwitchToTabArgs with Guid SessionId property
ActionArgs.h Updated SWITCH_TO_TAB_ARGS macro
AppActionHandlers.cpp Modified _HandleSwitchToTab() to find session and call FocusPaneBySessionId()
Tab.cpp Added FocusPaneBySessionId() - walks pane tree, calls _rootPane->FocusPane(pane)
Tab.h Declaration for FocusPaneBySessionId()
Resources.resw Added help string
TerminalPage.cpp Constructor call fix

Design decisions

  • GUID format flexibility: Accepts both 12345678-1234-... and {12345678-...} formats
  • Implicit window routing: Auto-implies -w 0 since session GUID uniquely identifies a pane
  • Pane focus: Focuses specific pane within split tabs
  • Mutual exclusion: --session excludes --target, --next, --previous

Validation Steps Performed

  • Builds successfully (ARM64 Release)
  • wt focus-tab --help shows new --session option
  • Single tab focus works
  • Multi-tab focus works
  • Split pane focus works (focuses specific pane)
  • IPC handoff from external process works
  • Invalid/non-existent GUID handled gracefully

PR Checklist

**Original Pull Request:** https://github.com/microsoft/terminal/pull/19784 **State:** closed **Merged:** No --- ## Summary of the Pull Request Adds a `--session` / `-s` option to the `wt focus-tab` command that accepts a `WT_SESSION` GUID. This allows external processes to programmatically focus the exact terminal tab and pane where a specific shell session is running. **Primary use case:** AI coding agents (GitHub Copilot CLI, Claude Code, Cursor, Aider, etc.) run long-running tasks in terminal sessions. When the task completes, users have often alt-tabbed away and opened many other tabs. This feature lets agents bring users back to the correct tab automatically: ```powershell # Agent saves session at startup $mySession = $env:WT_SESSION # ... long task runs, user alt-tabs away ... # Agent brings user back to the right place wt focus-tab --session $mySession ``` ## References and Relevant Issues - Fixes #19783 - Related: #17963 (WT_WINDOWID discussion) - Related: #16568 (programmatic terminal API) ## Detailed Description of the Pull Request / Additional comments ### Usage ```powershell wt focus-tab --session $env:WT_SESSION wt ft -s $env:WT_SESSION ``` ### What it does 1. **Finds the tab** containing the pane with the matching `WT_SESSION` GUID 2. **Switches to that tab** (routing to the correct window on the current desktop) 3. **Focuses the specific pane** if the tab has split panes ### Implementation | File | Change | |------|--------| | `AppCommandlineArgs.cpp` | Added `--session`/`-s` option with GUID parsing. Auto-sets `-w 0`. Updated `ValidateStartupCommands()`. | | `AppCommandlineArgs.h` | Added `_focusTabSession` member | | `ActionArgs.idl` | Extended `SwitchToTabArgs` with `Guid SessionId` property | | `ActionArgs.h` | Updated `SWITCH_TO_TAB_ARGS` macro | | `AppActionHandlers.cpp` | Modified `_HandleSwitchToTab()` to find session and call `FocusPaneBySessionId()` | | `Tab.cpp` | Added `FocusPaneBySessionId()` - walks pane tree, calls `_rootPane->FocusPane(pane)` | | `Tab.h` | Declaration for `FocusPaneBySessionId()` | | `Resources.resw` | Added help string | | `TerminalPage.cpp` | Constructor call fix | ### Design decisions - **GUID format flexibility:** Accepts both `12345678-1234-...` and `{12345678-...}` formats - **Implicit window routing:** Auto-implies `-w 0` since session GUID uniquely identifies a pane - **Pane focus:** Focuses specific pane within split tabs - **Mutual exclusion:** `--session` excludes `--target`, `--next`, `--previous` ## Validation Steps Performed - [x] Builds successfully (ARM64 Release) - [x] `wt focus-tab --help` shows new `--session` option - [x] Single tab focus works - [x] Multi-tab focus works - [x] Split pane focus works (focuses specific pane) - [x] IPC handoff from external process works - [x] Invalid/non-existent GUID handled gracefully ## PR Checklist - [x] Closes #19783 - [ ] Tests added/passed - [ ] Documentation updated - [ ] Schema updated (if necessary)
claunia added the pull-request label 2026-01-31 09:50:37 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
⛺ Reserved
A11yCO
A11yMAS
A11ySev1
A11ySev2
A11ySev3
A11yTTValidated
A11yUsable
A11yVoiceAccess
A11yWCAG
Area-Accessibility
Area-AtlasEngine
Area-AzureShell
Area-Build
Area-Build
Area-Chat
Area-CmdPal
Area-CodeHealth
Area-Commandline
Area-CookedRead
Area-DefApp
Area-Extensibility
Area-Fonts
Area-GroupPolicy
Area-i18n
Area-Input
Area-Interaction
Area-Interop
Area-Localization
Area-Output
Area-Performance
Area-Portable
Area-Quality
Area-Remoting
Area-Rendering
Area-Schema
Area-Server
Area-Settings
Area-SettingsUI
Area-ShellExtension
Area-ShellExtension
Area-ShellExtension
Area-Suggestions
Area-Suggestions
Area-TerminalConnection
Area-TerminalControl
Area-Theming
Area-UserInterface
Area-VT
Area-Windowing
Area-WPFControl
AutoMerge
Blocking-Ingestion
Culprit-Centennial
Culprit-WinUI
Disability-All
Disability-Blind
Disability-LowVision
Disability-Mobility
External-Blocked-WinUI3
Fixed
Gathering-Data
good first issue
HCL-E+D
HCL-WindowsTerminal
Help Wanted
Impact-Compatibility
Impact-Compliance
Impact-Correctness
Impact-Visual
In-PR
InclusionBacklog
InclusionBacklog-Windows TerminalWin32
InclusionCommitted-202206
Issue-Bug
Issue-Docs
Issue-Feature
Issue-Feature
Issue-Question
Issue-Samples
Issue-Scenario
Issue-Task
Needs-Attention
Needs-Author-Feedback
Needs-Bisect
Needs-Discussion
Needs-Repro
Needs-Tag-Fix
Needs-Tag-Fix
Needs-Triage
No-Recent-Activity
Priority-0
Priority-1
Priority-2
Priority-3
Product-Cmd.exe
Product-Colortool
Product-Colortool
Product-Colortool
Product-Conhost
Product-Conpty
Product-Meta
Product-Powershell
Product-Terminal
Product-WSL
pull-request
Mirrored from GitHub Pull Request
 Resolution-Answered
Resolution-By-Design
Resolution-Duplicate
Resolution-External
Resolution-Fix-Available
Resolution-Fix-Committed
Resolution-No-Repro
Resolution-Won't-Fix
Severity-Blocking
Severity-Crash
Severity-DataLoss
spam
this-will-be-a-breaking-change
Tracking-External
WindowsTerminal_Win32
Work-Item
zAskModeBug
zInbox-Bug
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
claunia
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/terminal#31958
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?