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
- Open iTerm2
- Go to Preferences > General > Magic
- Check Enable Python API
- 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
| Field | Type | Required | Description |
|---|---|---|---|
version |
string | No | Schema version (default: "1") |
name |
string | No | Workspace name |
tabs |
array | Yes | List of tab configurations |
Tab Configuration
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | Tab title in iTerm2 |
working_directory |
string | No | Default directory for panes |
layout |
object | No | Pane layout (omit for single pane) |
commands |
array | No | Commands for single-pane tabs |
Layout Configuration
| Field | Type | Required | Description |
|---|---|---|---|
split |
string | No | "vertical" or "horizontal" (default: "vertical") |
panes |
array | Yes | List of pane or nested layout objects |
Pane Configuration
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | No | Pane identifier |
working_directory |
string | No | Working directory |
commands |
array | No | Commands to execute |
delay |
float | No | Delay before running commands (seconds) |
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
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
itermspace-0.0.1.tar.gz
(54.2 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file itermspace-0.0.1.tar.gz.
File metadata
- Download URL: itermspace-0.0.1.tar.gz
- Upload date:
- Size: 54.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1111fd34ce39c35c4797c22f395c0a8fb2a0a429193b148c3ad94c073e42f302
|
|
| MD5 |
3b0fb5ae25a72babc3231f5fcead5e0c
|
|
| BLAKE2b-256 |
2f1c84a713767dd3af9f2279953f835121a6f48a690530526688b0ce88443c0c
|
Provenance
The following attestation bundles were made for itermspace-0.0.1.tar.gz:
Publisher:
publish-pypi.yml on midodimori/itermspace
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
itermspace-0.0.1.tar.gz -
Subject digest:
1111fd34ce39c35c4797c22f395c0a8fb2a0a429193b148c3ad94c073e42f302 - Sigstore transparency entry: 854648259
- Sigstore integration time:
-
Permalink:
midodimori/itermspace@3b762747a2a2252cab2ab221f49a7f0b86b27942 -
Branch / Tag:
refs/tags/v0.0.1 - Owner: https://github.com/midodimori
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish-pypi.yml@3b762747a2a2252cab2ab221f49a7f0b86b27942 -
Trigger Event:
release
-
Statement type:
File details
Details for the file itermspace-0.0.1-py3-none-any.whl.
File metadata
- Download URL: itermspace-0.0.1-py3-none-any.whl
- Upload date:
- Size: 11.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
aaf3f8737c969df92146e36edc90ac00a14ad6136af98060bd3c99c3372995a9
|
|
| MD5 |
59742cbc090f3484d2946d5f4f9d8985
|
|
| BLAKE2b-256 |
4847c8eeed13972874acf14d915f52081098d182b340d6ef94178995a3541fef
|
Provenance
The following attestation bundles were made for itermspace-0.0.1-py3-none-any.whl:
Publisher:
publish-pypi.yml on midodimori/itermspace
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
itermspace-0.0.1-py3-none-any.whl -
Subject digest:
aaf3f8737c969df92146e36edc90ac00a14ad6136af98060bd3c99c3372995a9 - Sigstore transparency entry: 854648298
- Sigstore integration time:
-
Permalink:
midodimori/itermspace@3b762747a2a2252cab2ab221f49a7f0b86b27942 -
Branch / Tag:
refs/tags/v0.0.1 - Owner: https://github.com/midodimori
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish-pypi.yml@3b762747a2a2252cab2ab221f49a7f0b86b27942 -
Trigger Event:
release
-
Statement type:
