termprofiles 0.1.0

Per-project terminal profiles for iTerm2 (macOS) and Windows Terminal (Windows), safely via per-file JSON.

termprofiles

Per-project terminal profiles that feel native on macOS (iTerm2) and Windows (Windows Terminal), without hand-editing JSON.

TermProfiles creates one JSON file per project so you can add or remove profiles safely. On macOS, each project gets its own ZDOTDIR (history + .zshrc), while Windows users receive tidy Windows Terminal fragments. Everything lives inside your home directory.

Contents

• Overview
• Supported Platforms & Requirements
• Installation
• Quick Start
• Command Reference
• How Profiles Are Structured
• macOS Details
• Windows Details
• Configuration & Environment Variables
• Example Workflows
• Troubleshooting & FAQ
• Uninstalling
• Contributing
• License

Overview

• Per-project profiles: Generates one dynamic profile (macOS) or fragment (Windows) per directory.
• Safe JSON handling: Files are written atomically with UTF-8 encoding to avoid corruption.
• No tmux required: Launch directly into the project directory with your preferred shell.
• Easy cleanup: termprofiles remove deletes the generated JSON (and optional macOS ZDOTDIR).
• Discoverable: termprofiles list shows exactly what was created.

Supported Platforms & Requirements

macOS

• macOS 11 or newer recommended.
• iTerm2 with Dynamic Profiles enabled.
• Shell: /bin/zsh is used, but you can customize via the generated .zshrc.

Windows

• Windows 10 19041+ or Windows 11 with Windows Terminal 1.16 or newer.
• PowerShell installed (default). Optional: Git Bash, Command Prompt, or WSL.

Installation

Using pipx (recommended)

pipx installs packages in isolated virtual environments and adds entry points to your shell.

# macOS (optional helper if Homebrew is available)
brew install pipx
pipx ensurepath
exec $SHELL

# macOS or Windows
pipx install termprofiles
# Upgrade later
pipx upgrade termprofiles

Verify the installation:

termprofiles --help

Using pip

If you prefer a virtual environment or user-site install:

python -m venv .venv  # optional virtual environment
source .venv/bin/activate  # Windows: .venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install termprofiles

From source

git clone https://github.com/yaioyaio/termprofiles.git
cd termprofiles
pipx install .  # or: python -m pip install .

Quick Start

macOS (iTerm2)

1. Run termprofiles add /path/to/project.
2. Reopen iTerm2 (or Profiles → Other Actions → Reload All Profiles).
3. Launch the new profile named proj-<slug>.
4. Enjoy an isolated .zshrc and history backed by ~/.zsh-profiles/<slug>/.

Example:

termprofiles add ~/dev/sample-app

Outputs something like Added: proj-sample-app and creates dp-sample-app.json in iTerm2's DynamicProfiles directory.

Windows (Windows Terminal)

1. Run PowerShell as the user (no admin needed).
2. Execute termprofiles add "C:\\src\\sample-app".
3. Close and reopen Windows Terminal (or run wt.exe again).
4. Select the new profile proj-sample-app from the dropdown.

By default the profile uses PowerShell and opens in your project directory.

Command Reference

termprofiles add <dir> [<dir> ...]

Create profiles for one or more project directories.

macOS options:

• --parent-guid GUID — inherit UI from an existing iTerm2 profile.
• --parent-name NAME — locate a profile by name (case-insensitive) and use its GUID.

Windows options:

• --color-scheme NAME — apply an existing Windows Terminal color scheme.
• --shell TYPE — powershell (default), cmd, git-bash, wsl, wsl:<alias>.
• --wsl-distro NAME — WSL distribution to launch (default Ubuntu).
• --wsl-zdotdir PATH — export ZDOTDIR before starting zsh in WSL.

termprofiles remove <target> [<target> ...]

Delete generated profiles. Each target can be the original directory or its slug.

• macOS: add --keep-zdotdir to preserve ~/.zsh-profiles/<slug>.
• Windows: only the fragment JSON is removed.

termprofiles list

Show profiles discovered via the generated JSON files. Helpful for auditing or scripting.

termprofiles parents (macOS only)

Enumerate iTerm2 profiles detected in ~/Library/Preferences/com.googlecode.iterm2.plist with their GUIDs.

How Profiles Are Structured

• Slug generation: The directory name is lowercased, spaces become -, and non-alphanumeric characters are stripped (e.g., /Users/Alex/My App → my-app).
• File naming:
  • macOS: ~/Library/Application Support/iTerm2/DynamicProfiles/dp-<slug>.json
  • Windows: %LOCALAPPDATA%\Microsoft\Windows Terminal\Fragments\TermProfiles\proj-<slug>.json
• Idempotent: If a JSON file already exists, the command prints Skip (exists) and leaves your configuration untouched.

macOS Details

• Each project gets ~/.zsh-profiles/<slug>/ containing .zshrc and .zsh_history.
• .zshrc sources ~/.zshrc.common if present, so you can share aliases across projects.
• History is unlimited up to 50k entries (HISTSIZE + SAVEHIST).
• Launch command: /usr/bin/env ZDOTDIR="<project_zdotdir>" /bin/zsh -l.
• If you set a parent profile, the generated dynamic profile inherits colors, fonts, and other UI settings from it.

Windows Details

• Fragment JSON conforms to the Windows Terminal fragment spec and is auto-discovered on launch.
• --shell wsl runs wsl.exe -d <distro>; combine with --wsl-zdotdir to export ZDOTDIR and spawn zsh via bash -lc.
• --shell git-bash points to the default Git for Windows install path ("C:\\Program Files\\Git\\bin\\bash.exe" -li). Adjust manually if you installed Git elsewhere.
• startingDirectory is set to the project path; Windows Terminal respects it for local shells and translates for WSL.

Configuration & Environment Variables

Every CLI flag has an environment variable equivalent (useful for shell rc files or CI scripts):

Purpose	Flag	Environment Variable	Default
iTerm2 parent GUID	--parent-guid	TP_PARENT_GUID	None
iTerm2 parent name	--parent-name	TP_PARENT_NAME	None
Windows color scheme	--color-scheme	TP_COLOR_SCHEME	None
Windows shell	--shell	TP_SHELL	powershell
WSL distro	--wsl-distro	TP_WSL_DISTRO	Ubuntu
WSL ZDOTDIR export	--wsl-zdotdir	TP_WSL_ZDOTDIR	None

Command-line arguments take precedence over environment variables. Set them in your shell profile to create customized defaults, e.g.:

export TP_PARENT_NAME="Solarized Dark"
export TP_COLOR_SCHEME="One Half Dark"

Example Workflows

• Automate profile creation: find ~/Code -maxdepth 1 -type d -not -path '*/.*' -print0 | xargs -0 termprofiles add.
• Shared look & feel: on macOS set TP_PARENT_NAME to your favorite theme; on Windows set TP_COLOR_SCHEME to keep colors consistent.
• WSL development: termprofiles add "/mnt/c/dev/app" --shell wsl --wsl-distro Ubuntu-22.04 --wsl-zdotdir "/home/user/.config/zsh/app" launches straight into WSL zsh with project-specific config.
• Clean removal: termprofiles remove ~/dev/sample-app --keep-zdotdir keeps historical context while removing the dynamic profile.

Troubleshooting & FAQ

• Profiles are missing. Restart iTerm2/Windows Terminal so it reloads dynamic profiles/fragments.
• iTerm2 cannot read the JSON. Ensure Dynamic Profiles are enabled (Preferences → Profiles → Other Actions → Import JSON Profiles).
• Windows Terminal ignores the profile. Confirm fragments are enabled (Settings → Open JSON file should list TermProfiles). Check %LOCALAPPDATA%\Microsoft\Windows Terminal\Fragments\TermProfiles for the created JSON.
• Parent profile not found (macOS). Use termprofiles parents to list available names and GUIDs. Remember that matching is case-insensitive and trims whitespace.
• Custom shells. For Windows Git Bash installs in a different location, copy the generated fragment, edit commandline, or pass a custom path by editing the JSON after creation.
• Unrecognized directory. termprofiles add skips paths that are not directories and prints Skip (not a dir).

Uninstalling

• Remove generated JSON: run termprofiles remove <targets> (and optionally delete ~/.zsh-profiles/<slug>).
• Delete the package:
  • pipx: pipx uninstall termprofiles
  • pip/virtualenv: python -m pip uninstall termprofiles
• Clean up leftover directories if desired: rm -rf ~/Library/Application Support/iTerm2/DynamicProfiles/dp-*.json (macOS) or delete the fragments folder on Windows.

Contributing

• Issues and pull requests welcome at GitHub.
• Local setup:

  git clone https://github.com/yaioyaio/termprofiles.git
  cd termprofiles
  python -m venv .venv
  source .venv/bin/activate
  python -m pip install --upgrade pip
  python -m pip install -e .
  termprofiles --help
  

• Run formatting and packaging checks as needed (python -m build).
• Follow conventional Python best practices and keep documentation updated.

License

MIT © yaioyaio