From e0bea0cac4ac7dd3ffd98977dfa1f572be10993e Mon Sep 17 00:00:00 2001
From: Jackie Li <jackie.space@gmail.com>
Date: Sat, 25 Oct 2025 18:11:57 +0100
Subject: [PATCH] add doc + changelog

---
 docs/changelog.rst |  5 +++++
 docs/sessions.rst  | 14 ++++++++++++++
 2 files changed, 19 insertions(+)

diff --git a/docs/changelog.rst b/docs/changelog.rst
index aac698a98..345d147b2 100644
--- a/docs/changelog.rst
+++ b/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]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/sessions.rst b/docs/sessions.rst
index 5fc62d5b2..d0719f99a 100644
--- a/docs/sessions.rst
+++ b/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`.