Allows you to save & restore kitty sessions, with all kitty OS windows, kitty tabs & kitty windows restored.
Doesn’t restore OS window sizes. See here for Window Workspace Placement Save & Restore.
Requires python 3 and kitty.
# Dump the current kitty session:
$ kitty @ ls > kitty-dump.json
# Convert this JSON file into a kitty session file:
$ cat kitty-dump.json | python3 ./kitty-convert-dump.py > kitty-session.kitty
# Start kitty from that session file:
$ kitty --session kitty-session.kittyWARNING: the kitty @ ls command will dump the state of the current kitty instance only!
While this seems simple, it gets more complicated when you want to get the state of all kitty instances, and/or want to do it from an automated script outside the kitty instance itself. The desktop/launcher files that ship with kitty launch a new instance every time kitty is opened. And you need remote control access to be able to query the state of an instance from outside the instance itself (where an automated script would run).
The kitty-convert-dump.py also takes an optional --no-copy-env argument. Copying the environment from the current windows can be very brittle and cause unexpected effects, especially after a reboot. If you run into problems, you can enable this option. Even when not enabled, the environment being copied is still just the same as the kitty --copy-env is aware of, which is the state only at instance start.
You will first need to be sure kitty is configured to allow remote control access. This can only be done in the kitty.conf by setting the allow_remote_control_access option, and it needs to be set to one of: socket-only, socket, or yes.
You will also need to configure kitty to create sockets with a known name/location. The listen_on directive in the kitty.conf file is used for this. The automation tools only support unix sockets, so these always need to have the protocol prefix unix:.
You can create socket files in a known folder location by setting the path and name, making sure to include the kitty-placeholder {kitty_pid} somewhere in the file name. However you’ll want this to be a non-persistent location or you’ll slowly accumulate broken socket files whenever you reboot without all kitty instances being shut down.
You can also create datagram sockets instead (localhost-only sockets). These are created by setting the name starting with @, and must have a globally unique name that can be differentiated from the other datagram sockets on the system. Usually just including kitty in the name somewhere will ensure that uniqueness though.
Examples:
# using socket files (warning, this location will result in slowly accumulating broken socket files)
listen_on unix:${HOME}/.cache/kitty/sessions/{kitty_pid}.sock
# using datagram sockets
listen_on unix:@kitty-{kitty_pid}.sock|
Warning
|
The listen_on settting must refer to an existing directory when using socket files. It will not create the folder for you.
|
The tools rely on knowing the directory to save the sessions into, and the pattern used to name the sockets (datagram or file). Either modify the default vaules at the top of the common.incl file, or set them in the environment whenever calling the script.
KITTY_SESSION_SOCK_PATTERN: Should match the listen_on kitty config setting, without the unix: protocol prefix.
KITTY_SESSION_SAVE_DIR: The directory where the saved session files are stored. This will be created if it doesn’t exist. It should be a dedicated location since it will be removed and replaced whenever an update to the saved sessions occurs.
Three scripts are provided for direct use: kitty-save-session-all.sh, kitty-save-session-restore-all.sh, and kitty-save-session-remove-inactive.sh.
These scripts all rely on the configuration variables remaining the same between every call to them, but provide straighforward functionality as indicated by their names.
The kitty-save-session-all.sh just loops thru the list of sockets kitty has created, queries each instance state from them, converts the output to a saved session file into a temp folder, and then replaces the KITTY_SESSION_SAVE_DIR with the temp folder. If there are no kitty instances running however, it will not do any cleanup of saved session files.
Additionally, this script supports an optional KITTY_SESSION_SAVE_OPTS variable that can be set to any space-separated list of arguments that should be passed to the python script performing the conversion to the kitty session syntax. See the help output of it for the available options.
Errors saving the state of kitty sessions are handled uniquely for socket files vs datagram sockets. Socket files may be in a persistent location that results in an increasing number of broken socket files from kitty sessions that weren’t terminated cleanly. When socket files are detected as the form being used, any successful saving of a session is considered an overall success, and broken sockets will generate error output but won’t cause the overall call to fail. Datagram sockets however will fail on the first failed attempted read from the socket.
The kitty-save-session-restore-all.sh just loops thru the list of saved session files, and runs a new instance of kitty for each. The kitty sessions are run asdetached sessions, which are independent of the calling shell the script was executed in. This will "restore" your sessions to the extent possible with kitty. Some setting do get unavoidably inherited from the calling shell, most notably the SHLVL variable, so restored sessions will usually appear to be at a deeper level of shell nesting than the originals. Also note that the PIDs of the new sessions cannot match the ones from the original sessions, so it’s inadvisable to immediately run kitty-save-session-remove-inactive.sh since all current saved sessions will appear unmatched by the restored instances.
The kitty-save-session-remove-inactive.sh script will remove any saved session files that don’t match currently running kitty instances. This is useful for cleaning up old saved session files you no longer want to restore, even when there are no instances currently running. Matching is based on PID, which restored sessions cannot match, so it’s advisable to instead use kitty-save-session-all.sh, which implicitly cleans up any inactive saved sessions as part of generating the new ones, after a kitty-save-session-restore-all.sh.
If you want to automatically save your kitty sessions against unexpected reboots, systemd can be used to create user unit files to automate the saving. Example files can be found in the systemd/ folder. They will need to be customized, put in ~/.config/systemd/user/, and enabled.
Customization needed:
In kitty-session-save.timer, set the frequency to update the saved sessions.
In kitty-save-session.service, modify the ExecStart to specify the absolute path to the kitty-save-session-all.sh script, and set KITTY_SESSION_SAVE_DIR, KITTY_SESSION_SOCK_PATTERN, and KITTY_SESSION_SAVE_OPTS environment variables to match your configuration, or you can configure the environment variables in your .profile or similar file and remove the definitions from this file, or you can directly modify the kitty-save-session-common.incl.
Optionally you can also enable notifications when kitty fails to save sessions by uncommenting the OnFailure line, then installing and modifying the kitty-save-session-notify-failed.service file as well.
The kitty-save-session-notify-failed.service is optional and only used if you uncommented the OnFailure line in the kitty-save-session.service file. This uses the noti tool, which you would need to install separately, to send notifications (default is a desktop notification). You must modify the ExecStart line to point to the absolute path where you’ve installed the noti tool, and can further modify what you want that notification to be. This service unit is only exected when saving sessions fails.
Assuming the files pointed to by the --session= option passed to kitty when calling kitty-save-session-restore-all.sh actually exist, they may be failing to parse due to particularly complex environment variables. The kitty session file format isn’t very robust, and doens’t allow anything more than relatively simplisitc environment variables to be included. The kitty-convert-dump.py is unable to handle all possible complexity, and merely quotes the environment variables in the kitty session file it generates.
Examine your saved session file to see if you have quotes within values or multi-line values being passed as --env arguments to launch commands.
Unfortunately with the --detach option necessary for the kitty restore, it’s not possible to check whether kitty successfully restored, or if it encountered an error loading the session file so it silently fails to restore the os window.
To avoid this issue, the only solution is to disable the inclusion of the environment in your saved sessions. This can be done by setting the KITTY_SESSION_SAVE_OPTS environment variable to --no-copy-env, which will disable environment copying as part of session saving.