itermspace

Launch iTerm2 workspaces from YAML configuration files.

Features

• Define terminal workspaces with multiple tabs
• Configure split panes in flexible grid layouts (vertical/horizontal)
• Set working directories and startup commands per pane
• Launch multiple config files at once
• Validate configurations before launching
• Dry-run mode to preview workspace setup

Requirements

• macOS (iTerm2 is macOS-only)
• iTerm2 with Python API enabled
• Python 3.13+

Enable iTerm2 Python API

1. Open iTerm2
2. Go to Preferences > General > Magic
3. Check Enable Python API
4. Accept the security warning

Installation

# Using uv (recommended)
uv tool install itermspace

# Or using pip
pip install itermspace

Usage

# Launch a workspace
itermspace workspace.yaml

# Launch multiple workspaces at once
itermspace backend.yaml frontend.yaml database.yaml

# Validate configuration(s)
itermspace --validate workspace.yaml
itermspace --validate *.yaml

# Preview without launching (dry-run)
itermspace --dry-run workspace.yaml

# Short alias
its workspace.yaml

Configuration

Create a YAML file defining your workspace:

version: "1"
name: "My Workspace"

tabs:
  - name: "Main"
    working_directory: "~/projects"
    layout:
      split: "vertical"
      panes:
        - name: "Editor"
        - name: "Terminal"
          commands:
            - "echo 'Ready!'"

See the examples/ directory for more configuration samples.

Configuration Reference

Root Level

Tab Configuration

Layout Configuration

Pane Configuration

Development

# Clone the repository
git clone https://github.com/midodimori/itermspace
cd itermspace

# Install dependencies
make install

# Run linting
make lint

# Run type checking
make typecheck

# Run tests
make test

License

MIT