i3-restore

A simple Python and Bash script to restore your i3 session. It works very similar to how Firefox restores a previous session. The script can correctly restore terminal subprocesses (such as Vim and ssh) and web browser instances exactly how they were before.

Table of Contents

• Features
• Getting Started
  • Dependencies
• Upgrading
• Configuring
• Automating The Script
  • Saving
  • Restoring
  • Restoring Programs In Assigned Workspaces
• Troubleshooting
• Contributing

Features

i3-restore has the following features (fill out a feature request for more to be added!):

• Configuration to save and restore desired terminals, web browsers, and terminal subprocesses from your latest i3 session
• Automatic saving and restoring of all i3 window layouts and programs running in your current i3 session
• Correct restoring of subprocesses within terminals (such as Vim and ssh) and web browser instances

Getting Started

Dependencies

• Python 3.7+
• Pip
• Jq
• Perl-anyevent-i3
• Xdotool

First, download the script onto your computer

git clone https://github.com/jdholtz/i3-restore.git
cd i3-restore

Next, install the needed packages for the script

pip install -r requirements.txt

Then, verify the script is working

./i3-save

Make sure to read the Configuring section before officially using the script to ensure programs specific to you are set up correctly (terminals, web browsers, etc.).

To get a more comprehensive understanding of what each mode in the script provides, run

./i3-save --help

or

./i3-restore --help

Upgrading

When upgrading this script, it is important to follow the Changelog for any actions that need to be performed, as many changes will not be made backwards compatible.

Check the version of the script

./i3-save --version

To upgrade, pull the latest changes from the repository

git pull

Again, verify the script is working

./i3-save

If you want the latest cutting edge features, you can use the develop branch. However, keep in mind that changes to this branch do not guarantee reliability nor are changes documented in the Changelog.

Configuring

To use the default configuration file, copy config.example.json to config.json.

For information on how to set up the configuration for your needs, see Configuration.md

Automating The Script

i3-restore can be automatically triggered every time i3 stops and starts. This is useful if you want to automatically restore your session after a restart or logging out. You can also configure the script to save your session on an interval to ensure you don't lose your current session layout if i3-save wasn't triggered.

Saving

To automatically save your session before exiting i3, simply trigger i3-save to run by putting it in your i3 configuration file. Example:

mode "exit: [l]ogout, [r]eboot, [h]ibernate, [s]leep, [p]oweroff" {
    bindsym l exec "/path/to/i3-restore/i3-save && i3-msg 'exit'"
    bindsym r exec "/path/to/i3-restore/i3-save && systemctl reboot"
    bindsym h exec systemctl hibernate
    bindsym s exec systemctl suspend
    bindsym p exec "/path/to/i3-restore/i3-save && systemctl poweroff"
    # Fallback if script fails to save
    bindsym Return exec i3-msg exit
    bindsym Escape mode "default"
}

Restoring

Similarly, you can also automatically restore your session upon starting i3. To do this, simply put this line in your i3 configuration file:

exec /path/to/i3-restore/i3-restore

To automatically save your session on an interval, pass the --interval flag into the script. You can also configure how often the save is triggered (it defaults to 10 minutes if no argument is passed in).

exec /path/to/i3-restore/i3-restore --interval <minutes>

Note: To restore web browsers correctly, you need to have their "Restore previous session" feature enabled

Restoring Programs In Assigned Workspaces

Some programs that take a few seconds to start (such as Discord) might not restore on the correct workspace. To mitigate this issue, simply use the assign function in i3 and add it to your i3 configuration file.

Troubleshooting

To troubleshoot a problem, run the script with the -v flag. This will display debug messages so you can get a better overview of the problem. Using -vv will print out all commands executed by the script so you can trace through it and understand where and why a problem is occurring.

If you run into any issues, please file it via GitHub Issues. Please attach any relevant logs (can be found in logs/i3-restore.log) to the issue. The logs may contain sensitive information such as directory names, program launch commands, and configuration settings, so make sure to remove any information you don't want to be shared before attaching them.

If you have any questions or discussion topics, start a GitHub Discussion.

Contributing

Contributions are always welcome. Please read Contributing.md if you are considering making contributions.