Preserve & Restore current session

[tymnim]

I really like this console and this is a bit of functionality that I found to be really missing Kitty.

Sometimes I really need to switch between projects when I am in the middle of something and sometimes that requires rebooting my computer. In that case I must bring everything I am working on to a stopping point and remember where I left off or to loose it.

I am looking for some for of session preservation and restoring method. Kind of what vim/neovim do with :mksession command and then :source or vim -S Session.vim. Completely restoring all the open files, butters, splits etc.

I would like to have some sort of option in the top bar next to the New OS Window, New Tab, Close Tab, etc - Save Current Session which would preserve all tabs from the current window, current scroll back in each buffer etc. So it can be saved in some file kitty_session.json and can be restored through Restore Session button by importing said file and would look like I never closed it.

Understanding all the limitations off it, all open active programs must be closed and only output from them must be saved. Me being completely unfamiliar with the technical difficulties of the implementation, my first instinct is "to save all the tabs and their content in the file and then when restoring each of them through the Kitty code, we could just pass the echo command to print what was on the screen zsh -i -c 'echo "<content of the entire buffer>"' - this is kind of the lazy option, it would be obviously better if all this was be handled inside Kitty and the shell was started after the buffer has been printed.

Let me know if I am missing something and there's already a work around it or if that would be a new feature which maybe I could contribute to, because having this functionality would be really sweet!

Cheers, Tim

[kovidgoyal]

See for example: https://github.com/dflock/kitty-save-session kitty provides the underlying tools to get the information, which thrid party tools can use to implement save/restore of sessions, but there is no builtin functionality for that as yet. If you are interested in implementing such functionality, you are welcome to work on it.

[mike-lloyd03]

@zzhaolei did you make any progress on this? I'm interested in contributing to this feature.

I think an approach something along these lines would work:

1. Implement the ability for kitty @ ls to output data in the startup session format OR allow the startup session feature to read the @ ls json.
2. Implement a timer for automatic session saving (zellij does this by default every 1 minute but is configurable)
3. Add configuration options like enable_session_management, session_directory, and session_save_frequency

Number 1 is mostly already done with kitty-save-session with the exception of split layouts. However, I think this approach would be somewhat hacky to implement in kitty itself. It would make more sense to me to just read from the existing json data output by @ ls format. I'm not sure how kitty internally manages state but I would imagine it is more similar to the @ ls data than the startup session format.

In early planning for Zellij's session management functionality, the goal was to simply serialize the application state, write it to a machine-readable format like json or toml, and deserialize that on the next startup. I'm not sure which route they ended up going in the end, but I think that'll be another good way to start and might avoid having to deal with translating between the @ ls and startup session syntax altogether.

[zzhaolei]

2. You can use Kitty's watcher

Overall, there is no progress. All tabs can be restored correctly, but the panes (windows) within the tabs cannot be restored correctly.

[zzhaolei]

This may require understanding splits.py

[kovidgoyal]

I will implement this (serialization/deserialization for layouts) when I get some time, I just have about a thousand other things to do as well, so be patient 😄 Once I have done this implementing sessions should be pretty trivial for anyone interested as all the other pieces are already there.

[mike-lloyd03]

I'd be happy to take a swing at it if you don't mind. I'll probably need some guidance, however. Perhaps if you could jot down a few notes to get me going in the right direction, I can see what I come up with. I'm not intending to rush you, just happy to contribute to kitty if it helps.

[kovidgoyal]

On Fri, Aug 01, 2025 at 10:48:19PM -0700, Mike Lloyd wrote: I'd be happy to take a swing at it if you don't mind. I'll probably need some guidance, however. Perhaps if you could jot down a few notes to get me going in the right direction, I can see what I come up with. I'm not intending to rush you, just happy to contribute to kitty if it helps.

I had a brief look and serialization is already implemented for splits. I cleaned it up and added unserialize. Now all you need to do is implement --output-format=session for kitten @ ls First, implement set_layout_state() aka unserialize for all the other layouts apart from splits. This should be pretty trivial. Once that's done and merged, to generate a session file using the serialize() function, you will convert each window in each tab into a launch command with --var=kitty_serialize_winid=<the window id> Finally you will need to implement a new command in session files, call it set_layout_state. It will take one argument, the JSON serialization of the layout state (be careful to serialize JSON without newlines). This implementation will be in session.py The implementation will simply call current_tab.current_layout.unserialize(state, map_window_id) Where map_window_id uses the kitty_serialize_winid like this: ```py d = {} for w in all_windows_in_tab: if x := w.user_vars.get('kitty_serialize_winid'): d[x] = w.id map_window_id = d.get ``` Have, fun!

[kovidgoyal]

Oh and you probably dont want to serialize popup overlay windows like confirmation prompts, unicode input, hints, etc. and the like. To implement that, in your serialization to session file code skip any windows that have actions_on_close, actions_on_removal or actions_on_focus. Such windows cannot be saved/restored correctly anyway as they depend on aritrary python functions in their actions.

At some point you will likely need to add save/restore for launch --watch as well.

[zzhaolei]

d = {}
for w in all_windows_in_tab:
   if x := w.user_vars.get('kitty_serialize_winid'):
      d[x] = w.id
map_window_id = d.get

How do get the all_windows_in_tab in a class Session?

[kovidgoyal]

On Sat, Aug 02, 2025 at 03:38:51AM -0700, zhaolei wrote: >```py >d = {} >for w in all_windows_in_tab: > if x := w.user_vars.get('kitty_serialize_winid'): > d[x] = w.id >map_window_id = d.get >``` How do get the `all_windows_in_tab` in a `class Session`?

You dont, you do it in the startup() method of the Tab class.

[mike-lloyd03]

Whelp I just tried to push a PR for implementing set_layout_state for the remaining layouts and it looks like Kovid beat me to it just a few days ago. I'll keep monitoring this and #8876 and helping out where I can.

[kovidgoyal]

On Wed, Aug 06, 2025 at 06:05:44PM -0700, Mike Lloyd wrote: Whelp I just tried to push a PR for implementing `set_layout_state` for the remaining layouts and it looks like Kovid beat me to it just a few days ago. I'll keep monitoring this and #8876 and helping out where I can.

Hah, well the remaining bit is just creating the session file, shouldn't be too hard.

[mike-lloyd03]

Do we not need set_layout_state for Stack?

[mike-lloyd03]

Looks like @zzhaolei is well on the way to implementing session serialization to file. I guess the next step would be to automate session tracking.

It sounds like a watcher is the way to go and perhaps using the on_focus_change callback. Though this could create a noticeable delay for users when switching tabs or windows.

So something like this might be enough:

def on_focus_change(boss: Boss, window: Window, data: dict[str, Any])-> None:
    boss.call_remote_control(window, ('ls', '--output-format', 'session'))
    # output result to the session file
    # we probably also need to get the startup session file here so we can overwrite it

But maybe it would be better if serialization happened on a timer. Perhaps every minute?

[kovidgoyal]

On Wed, Aug 06, 2025 at 09:38:51PM -0700, Mike Lloyd wrote: Do we not need `set_layout_state` for `Stack`?

Nope it has no state.

[kovidgoyal]

I'm not a fan of either timers or focus events, way too much overhead either way. If you want that it needs to be optional defaulting to off. The only automatic one would be when the OS sends a shutdown message to the application during logout/reboot/poweroff or when the user triggers application quit.

[zzhaolei]

I wrote this and need kitty night

import threading

from pathlib import Path
from typing import Any

from kitty.boss import Boss
from kitty.window import Window


path = Path("/tmp/kitty-session.conf").expanduser()
lock = threading.Lock()

def write_session(boss: Boss, blocking: bool = False):
    locked = lock.acquire(blocking=blocking)
    if not locked:
        return
    try:
        with open(path, "w") as f:
            f.write("\n".join(boss.serialize_state_as_session()))
    finally:
        lock.release()

def on_tab_bar_dirty(boss: Boss, window: Window, data: dict[str, Any]) -> None:
    write_session(boss)

[mike-lloyd03]

This is working great for me. Thank you. I'm trying to figure out a way to create different session files depending on which kitty OS window I'm in. I usually have two open (a main window and a dropdown window with t-drop)

I think writing a file called ~/.config/kitty/sessions/<window-name>.conf using using the window name passed when kitty starts (with --title) would do the trick. I'm just trying to figure out how to get that from boss and window.

[kovidgoyal]

On Fri, Aug 15, 2025 at 09:17:26AM -0700, Mike Lloyd wrote: Is the `on_tab_bar_dirty` watcher documented anywhere?

See launch.rst in the kitty sourcecode a version of kitty with it hasnt been released yet so it isnt the rendered docs.

[mike-lloyd03]

Thanks. Yeah I deleted the comment once I realized that was the case. It's working well for serialization for me.