How to Create Custom iTerm2 Window Arrangments

TL;DR Create a custom keyboard shorcut to automatically spawn a set of windows and splits with processes running.

iTerm2 shortcut screenshot

iTerm2 window layout screenshot

iTerm2 is very useful software, but this process is complicated. I've attempted to document known pitfalls.

How to Create a Custom Window Arrangement

  1. Close all iTerm2 windows.
    We'll be using the "Save Window Arrangement" feature which saves all windows. Any windows open in the background will also be saved.

  2. Open a new window and set up your tab and split layout as desired.
    Do not run any processes, nor cd into any directories yet. We'll do that in the next section. Just set up the layout of splits and tabs.

    ⌘D and ⌘ Shift D are useful shortcuts for creating vertical and horizontal splits.

  3. Create a new profile for each shell.
    This complicated and has several steps.

    • Open preferences with ⌘, (Command-Comma)
    • Go to the "Profiles" tab.
    • Create a new profile and name it something specific to this arrangement and shell, like "Work Build Process"

      New profile screenshot

    • Under "Send text at start" type the commands, including cd to the correct starting directory, for this shell to execute on startup. For example you might type cd ~/my-work-folder; npm run watch, which is what's executed in this shell. It's better to use ; between commands instead of && so that if any command fails, the rest still get executed.

    • Repeat this for every shell you want to have a custom command or custom working directory. For example, you might name your profile "Work Main Directory" that just contains the startup command cd ~/mywork-folder.
  4. Assign the correct profiles to the correct shells.

    • Right click on each shell and choose "Edit Session"

      Edit session screenshot

    • Choose your profile corresponding to this shell. You can also use this opportunity to give it a name, which will show up in the tab title. iTerm2 doesn't use profile names in the tabs, because why would it?!

      Set profile screenshot

    • After you click "Change Profile" you must close the preferences window.

      Warning 1: Hitting "Change Profile" doesn't give you any feedback that it worked.

      Warning 2: Setting the session will not run the commands you specified. I'm not kidding. You won't know if it worked until step 7.

  5. Save the window arrangement.
    Press ⌘ Shift S (Command-Shift-s) and then name your new arrangment.

  6. Assign a keyboard shortcut to open your arrangement.

    • Open the preferences again with ⌘, (Command comma).
    • Open the "Keys" tab.
    • Create a new shortcut using the + icon.
    • Highlight "keyboard shorcut" and press the keys you want to open this workspace. I prefer something like ⌘ Shift [First letter of arrangement] such as ⌘ Shift W to open my "Work" window arrangement.
    • For "Action", open the dropdown and scroll all the way to the bottom to "Select Menu Item".
    • Open the new "Menu Item" dropdown and scroll down to the "Window" section near the bottom, find the "Restore Window Arrangement" subsection, and select your profile.

      Create a keyboard shortcut screenshot

  7. Close all windows again and test your arrangement by triggering your keyboard shortcut!

Hopefully everything worked fine and you have a shortcut you can trigger to set up a custom arrangement!

Troubleshooting

There are a few pitfalls here.

If your startup commands don't work as expected then you have to modify your session profile commands, then you have to re-assign the profile to the shell. The profile doesn't live update, it somehow caches an old version of your shell commands. After modifying your shell commands, repeat the "Edit Session" steps including hitting "Change Profile." Then save your arrangement again and overwrite the old one with the same name. You can only test it by re-opening a new arrangement with the keyboard shortcut you set up. This is a mini nightmare. Feel free to ping @George Nachman about any frustrations you have!

After saving an arrangement, it might not show up in the menu item dropdown when creating a new keyboard shortcut. If this is the case, after you've saved your arrangement with ⌘ Shift S, you must restart iTerm2.

That's It!

If this helped you improve your iTerm2 workflow, consider following me on Twitter or buying me a coffee :).

comments powered by Disqus