install-workspace-launcher

name	install-workspace-launcher
description	Install or verify the iterm2-scripts workspace launcher (workspace-launcher.py) in iTerm2's AutoLaunch directory with full telemetry, customizable paths, and a foolproof verify/uninstall surface. Use when the user wants to set up the workspace launcher on a fresh macOS machine, verify an existing install, debug setup issues, or cleanly uninstall.

install-workspace-launcher

Foolproof installer for the iterm2-scripts workspace launcher. Designed for a fresh macOS machine where the user has Claude Code + iTerm2 and nothing else.

What it does

The skill invokes bin/install/install-workspace-launcher, a POSIX-sh entry point that runs six phases:

Phase	Purpose	Idempotent?
0	Detect runtime (macOS, iTerm2, xcode-select, uv, python3.13, git)	yes
1	Bootstrap missing prereqs (instructions only — never curl | sh)	yes
2	Clone the repo (or detect we're already inside it)	yes
3	Build bin/tab-picker/tab-picker via swiftc	yes
4	Wire AutoLaunch symlink + persist repo path	yes
5	Initialise ~/.config/workspace-launcher/preferences.toml (only if missing)	yes
6	Verify every post-condition; print summary	yes

Every shell command of consequence emits a structured JSONL event to ~/.local/state/workspace-launcher-install/install-<utc-iso>.jsonl.

How to invoke

The user types one of:

/install-workspace-launcher              # full install (6 phases: detect → bootstrap → fetch → build → wire → verify)
/install-workspace-launcher --verify     # check existing install (Phase 6 only, no changes)
/install-workspace-launcher --uninstall  # remove symlinks; preserve user data
/install-workspace-launcher --dry-run    # preview plan without fetch/build/wire/config (detect only)
/install-workspace-launcher --debug      # verbose mode + DEBUG-level logs
/install-workspace-launcher --quiet      # suppress stdout; write logs only

Additional flags (can combine with above):

/install-workspace-launcher --skip-swift-build  # skip Phase 3 (swiftc native tab-picker binary compile)

The skill resolves the entry-point script path (preferring the repo's bin/install/ directory if running inside the repo, otherwise cloning a fresh copy first) and execs it.

Customisation

CLI flags and environment variables (precedence: CLI flag > env var > built-in default):

Flag / Env Var	Default
--repo-url / WL_REPO_URL	https://github.com/terrylica/iterm2-scripts
--target-dir / WL_TARGET_DIR	~/Library/Application Support/iTerm2/Scripts/AutoLaunch
--config-dir / WL_CONFIG_DIR	~/.config/workspace-launcher
--log-dir / WL_LOG_DIR	~/.local/state/workspace-launcher-install
--skip-swift-build / WL_SKIP_SWIFT_BUILD=1	(disabled)
--debug / WL_DEBUG=1	(disabled)
--quiet / WL_QUIET=1	(disabled)

Example (env vars):

WL_TARGET_DIR=~/custom/iterm2 WL_SKIP_SWIFT_BUILD=1 /install-workspace-launcher

Note: --skip-swift-build skips compilation of bin/tab-picker/tab-picker (native macOS tab selector binary). Useful on machines without Xcode Command Line Tools or when you prefer the SwiftDialog fallback UI.

Trust boundary (verify before installing from a fork): when you pass --repo-url pointing at any repo other than the canonical terrylica/iterm2-scripts, you are trusting that fork to:

1. Run swiftc against its bin/tab-picker/*.swift sources, and
2. Symlink the resulting binary into iTerm2's AutoLaunch directory — meaning the binary is invoked the next time iTerm2 starts.

Audit the fork's diff against upstream first. For untrusted exploration, pair --repo-url with --skip-swift-build so no fork-supplied code is compiled or executed.

Exit codes

Code	Meaning
0	Success
1	User cancelled OR concurrent install active
2	Missing prereq (git, uv, xcode-select, etc)
3	Build failure (swiftc compile failed)
4	Wiring failure (symlink or config failed)
5	Verification failure (post-conditions broke)
6	--verify only: no install present yet

Telemetry & provenance

All events are local-only — nothing is transmitted upstream. The log file is the audit trail. Tail it live with:

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

Workflow for the assistant

1. Read this file (you're doing it).
2. Locate bin/install/install-workspace-launcher. If running inside the iterm2-scripts repo, use ./bin/install/install-workspace-launcher. Otherwise the entry script clones the repo first.
3. Forward any flags the user passed verbatim.
4. Stream stdout to the user. On failure, surface the last 5 lines of the log file with file path so the user can investigate.
5. On success, print the summary table the script emits.