add doc + changelog

docs/changelog.rst

@@ -184,6 +184,11 @@ Detailed list of changes
 - Fix a regression in 0.43.0 that caused :opt:`tab_bar_margin_width` to be
   doubled on the right edge of the tab bar (:iss:`9154`)
 
+- Session files: Add a new ``focus_tab`` command to specify which tab should be
+  active when a session is loaded. Accepts either a plain number (0-based index)
+  or a match expression for flexible tab selection, allowing sessions to preserve
+  the active tab state (:doc:`sessions`)
+
 0.43.1 [2025-10-01]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/sessions.rst

@@ -154,6 +154,13 @@ all the major keywords you can use in kitty session files:
     focus_os_window
     launch emacs
 
+    # Create another tab
+    new_tab logs
+    launch tail -f /var/log/syslog
+
+    # Focus the first tab (index 0) when the session loads
+    focus_tab 0
+
     # Create a complex layout using multiple splits. Creates two columns of
     # windows with two windows in each column. The windows in the first column are
     # split 50:50. In the second column the windows are not evenly split.
@@ -272,6 +279,13 @@ documentation for them.
     otherwise the window manager might block changing focus to prevent *focus
     stealing*.
 
+``focus_tab [tab index]``
+    Set which tab should be active (focused) in the current OS Window. The tab
+    index is 0-based, so ``focus_tab 0`` will focus the first tab, ``focus_tab 1``
+    the second tab, and so on. This is useful for session files that create
+    multiple tabs and want to ensure a specific tab is active when the session
+    is loaded.
+
 ``enabled_layouts comma separated list of layout names``
     Set the layouts allowed in the current tab. Same syntax as
     :opt:`enabled_layouts`.