Workspace Launcher for iTerm2

Workspace automation for iTerm2 using the official Python API. Creates consistent split-pane layouts on iTerm2 startup with workspace selector, tab customization, and git worktree discovery.

Also includes TextHelix.app - a macOS app that opens text files in Helix editor via iTerm2.

---

Install (autonomous, via Claude Code) ⭐ Recommended

If you're using Anthropic's Claude Code CLI, run:

/install-workspace-launcher

This autonomous skill installs workspace-launcher.py to iTerm2's AutoLaunch directory in one go. It handles all prerequisites (Xcode CLT, uv, Python 3.13, git), clones the repo, builds native binaries, and verifies post-conditions. Full telemetry is written to ~/.local/state/workspace-launcher-install/install-<utc-iso>.jsonl for debugging.

Modes:

Command	Purpose
/install-workspace-launcher	Full install (detect → bootstrap → fetch → build → wire → verify)
/install-workspace-launcher --verify	Check existing install; no changes
/install-workspace-launcher --uninstall	Remove symlinks; preserve configs
/install-workspace-launcher --dry-run	Preview plan without making changes

Universal toolchain required: git, uv, swiftc (Xcode CLT), POSIX sh. No Homebrew dependency — all tools are either pre-installed or auto-installed by the skill.

For debugging, check the telemetry log:

tail -f ~/.local/state/workspace-launcher-install/install-*.jsonl

---

Quick Start (Claude Code CLI) ⭐ Alternative

If you prefer Claude's general assistance without the autonomous installer:

git clone https://github.com/terrylica/iterm2-scripts
cd iterm2-scripts
claude

Then tell Claude what you want:

You say...	Claude will...
"Set up the workspace launcher"	Run setup.sh, configure iTerm2, create symlinks
"Build TextHelix.app"	Install Platypus, run build-texthelix, guide Gatekeeper bypass
"Create a new workspace"	Run the setup wizard or help edit TOML configs
"Help me customize tabs"	Explain the config format and edit files

Claude reads the project's CLAUDE.md files automatically and knows how to:

• Install dependencies (Python, Homebrew packages)
• Configure iTerm2 Python API
• Build and troubleshoot TextHelix.app
• Customize workspace configurations

---

Manual Installation

Option 1: Git Clone (Recommended)

git clone https://github.com/terrylica/iterm2-scripts
cd iterm2-scripts && bash setup.sh

Option 2: Direct Execution

# Run directly with uv (no installation needed)
uv run https://raw.githubusercontent.com/terrylica/iterm2-scripts/main/workspace-launcher.py

Option 3: Quick Install Script

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/terrylica/iterm2-scripts/main/install.sh)"

Prerequisites

• macOS (tested on macOS 14+)
• iTerm2 (version 3.5+)
• Python 3.13 (brew install python@3.13)
• uv package manager (brew install uv)

Setup

1. Enable Python API in iTerm2: iTerm2 → Settings → General → Magic → Enable Python API

2. Restart iTerm2 - the workspace launcher will run automatically

3. Verify setup (optional): iTerm2 → Scripts → AutoLaunch → should show workspace-launcher.py

Configuration

Configuration files live in ~/.config/workspace-launcher/:

# ~/.config/workspace-launcher/workspace-default.toml

[layout]
left_pane_ratio = 0.25
settle_time = 0.3

[commands]
left = "ls -la"    # Or: br --sort-by-type-dirs-first (requires broot)
right = "zsh"      # Or: claude (requires Claude Code CLI)

[[tabs]]
name = "home"
dir = "~"

[[tabs]]
name = "projects"
dir = "~/projects"

Features

• Workspace Selector: Choose from multiple workspace configurations on startup
• Tab Customization: Select which tabs to open each session, reorder tab positions
• Git Worktree Discovery: Automatically discovers worktrees from all git repos
• Scan Folders: Configure which directories to scan for repositories
• Workspace Management: Enable/disable, delete, or create workspaces via Manage menu
• Snapshot Capture: Save current iTerm2 tabs as a new workspace configuration
• Setup Wizard: Guided first-run setup and on-demand workspace creation
• Migration Support: Automatically migrates from legacy ~/.config/iterm2/ path
• SwiftDialog UI: Enhanced dialogs when SwiftDialog is installed

Required Homebrew Packages

brew install swiftdialog  # Workspace selector and tab customization dialogs
brew install broot        # File navigator for left pane

These are installed automatically by setup.sh if Homebrew is available.

TextHelix.app

macOS application that opens text files in Helix editor via iTerm2. Useful for:

• Setting Helix as default editor for .md, .py, .toml, etc.
• Opening files from Finder in a new iTerm2 window with Helix

Build with Claude Code:

claude
# Say: "Build TextHelix.app"

Or build manually:

brew install --cask platypus
# Install CLI: Platypus.app → Settings → Install Command Line Tool
./bin/build-texthelix

See platypus/CLAUDE.md for full instructions.

---

For Claude Code CLI Users

See CLAUDE.md for detailed instructions on:

• Project architecture and build system
• Development workflow with mise
• Contribution guidelines

---

License

MIT