Andy Ray's Blog

By following these steps, we'll learn how to create a custom keyboard shortcut to automatically spawn a set of windows and splits with processes running.

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

How to Create a Custom Window Arrangement

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

Open a new window and set up your tab and split layout as desired.
Don't 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.

1. Create a new profile for each shell.
   This is 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"

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.

You can also use the "directory" radio button, and not use the cd A; do B; syntax. I've found that sometimes iTerm will run the "send text at start" before it opens that directory though. This may have gotten better in later versions.

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.

1. Assign the correct profiles to the correct shells.

Right click on each shell and choose "Edit Session"

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?!

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.

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

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 shortcut" 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.

1. 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.

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.

The creator @George Nachman is responsive on Twitter for iTerm2 questions.

That's It!

If this helped you improve your iTerm2 workflow, consider following me on Twitter.