remove --focus-tab and add docs

docs/changelog.rst

@@ -189,6 +189,10 @@ Detailed list of changes
   or a match expression for flexible tab selection, allowing sessions to preserve
   the active tab state (:doc:`sessions`)
 
+- :ac:`save_as_session`: Add ``--base-dir`` option to specify a base directory
+  for saving session files with relative paths, useful when the current working
+  directory is not the desired location (:doc:`sessions`)
+
 0.43.1 [2025-10-01]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/sessions.rst

@@ -102,6 +102,17 @@ for a path at which to save the session file. Specify the path and the session
 will be saved there with the exact setup you created. The saved file will even
 be opened in your editor for you to review, automatically.
 
+.. tip::
+   If you want session files to be saved to a specific directory regardless of
+   your current working directory, use the ``--base-dir`` option. For example::
+
+       map f7>s save_as_session --use-foreground-process --base-dir ~/.local/share/kitty/sessions
+
+   This is particularly useful when kitty is launched from system-wide shortcuts
+   where the working directory might not be your home directory. Note that
+   ``--relocatable`` is typically not used with ``--base-dir``, since relocatable
+   is meant for session files that are co-located with their project directories.
+
 If instead, you want to create these by hand, see the example below which shows
 all the major keywords you can use in kitty session files:
 

kitty/session.py

@@ -631,12 +631,10 @@ use :code:`--match=session:.`.
 
 --base-dir
 When specified, relative session filenames will be saved to this directory instead of the current
-working directory. Absolute paths are not affected by this option.
+working directory. This is useful when kitty is launched from locations where the working directory
-
+is not your home directory, such as from system-wide shortcuts. Note that :code:`--relocatable` is
-
+typically not used with :code:`--base-dir`, since relocatable is meant for session files that are
---focus-tab
+co-located with their project directories.
-type=bool-set
-When enabled, add a focus_tab command to the saved session file to preserve the currently active tab.
 '''
 
 
@@ -649,7 +647,10 @@ def save_as_session_part2(boss: BossType, opts: SaveAsSessionOptions, path: str)
         base_dir = os.path.abspath(os.path.expanduser(opts.base_dir))
         path = os.path.join(base_dir, path)
     path = os.path.abspath(os.path.expanduser(path))
-    session = '\n'.join(boss.serialize_state_as_session(path, opts))
+    # When --base-dir is specified, use it as the session_path for relocatable calculation
+    # This makes relative paths relative to base_dir instead of the session file location
+    session_path_for_serialize = os.path.join(opts.base_dir, 'dummy') if opts.base_dir else path
+    session = '\n'.join(boss.serialize_state_as_session(session_path_for_serialize, opts))
     os.makedirs(os.path.dirname(path), exist_ok=True)
     atomic_save(session.encode(), path)
     if not opts.save_only:

kitty/tabs.py

@@ -1317,10 +1317,7 @@ class TabManager:  # {{{
             hmap[at.id] = len(self.active_tab_history) + 1
         def skey(tab: Tab) -> int:
             return hmap.get(tab.id, -1)
-        active_tab_index = -1
+        for tab in sorted(self, key=skey):
-        for i, tab in enumerate(sorted(self, key=skey)):
-            if tab is self.active_tab:
-                active_tab_index = i
             ans.extend(tab.serialize_state_as_session(session_path, matched_windows, ser_opts))
         if ans:
             prefix = [] if is_first else ['', '', 'new_os_window']
@@ -1329,10 +1326,6 @@ class TabManager:  # {{{
             if self.wm_name and self.wm_name != appname:
                 prefix.append(f'os_window_name {self.wm_name}')
             ans = prefix + ans
-            # Add focus_tab command if --focus-tab option is enabled
-            if ser_opts.focus_tab and active_tab_index >= 0:
-                ans.append('')
-                ans.append(f'focus_tab {active_tab_index}')
         return ans
 
     @property