iTerm2 Shell Integration
https://github.com/gnachman/iterm2-shell-integration- Category
- Developer Tools
- Rank
- No. 907Tools index
- Pricing
- Open Source
- Type
- TOOL
- Builder
- gnachman
- GitHub
- 70 stars
- Date
About
Shell integration scripts and utilities for iTerm2 — adds inline images, command marking, file transfer, and more to your terminal.
What it does
A command-line companion suite that lets terminal sessions exchange structured data with iTerm2. Its scripts encode files, images, environment details, Git state, and remote command context into terminal control sequences. A Python client also proxies commands from an SSH host back to the local application over a Unix socket.
Why it's ranked here
The strongest case is breadth paired with practical protocol handling. The utilities accept files, URLs, and standard input, account for tmux framing, and preserve remote command output and exit status. The sparse top-level documentation and mixed runtime requirements make discovery and setup less approachable than the underlying code deserves.
What's good
The remote Python client uses only the standard library, carries terminal dimensions and working-directory context, and handles cancellation, broken pipes, malformed frames, stalled payloads, and premature disconnects. Image and text tools support sizing or type hints, URLs, pipes, and tmux-safe chunking. Git integration exposes branch, cleanliness, divergence, and change counts to the terminal.
Tradeoffs
This is a collection of shell, Python, and Perl utilities rather than one uniform package. Some commands depend on external programs such as base64, tar, curl, Git, or image-dimension helpers. The API utility separately requires the iTerm2 Python module. Several features rely on iTerm2-specific control sequences, so they are not general terminal enhancements.
How to use it well
It suits iTerm2 users who work heavily in shells, especially across SSH or tmux, and want richer file viewing, transfers, repository status, or remote application control. Add only the utilities that match recurring terminal tasks and verify their local dependencies. It does not replace a general SSH client, cross-terminal protocol layer, package manager, or full Git interface.
Technical notes+
shell_integration/it2.py is a Python 3.7+ stdlib-only Unix-domain-socket client using one-byte frame types and four-byte big-endian lengths; it forwards argv, cwd, TERM, TTY state, and terminal size, caps declared frames at 256 MiB, and applies a 30-second whole-payload deadline. utilities/imgcat, utilities/it2cat, utilities/it2dl, and utilities/it2ul emit OSC 1337 sequences, with tmux wrapping and base64 portability handling. utilities/imgls is Perl 5.14 code that augments listings with thumbnails and optional dimensions. utilities/it2api uses asyncio and the external iterm2 module. utilities/it2git publishes Git state as user variables. utilities/it2ssh wraps interactive SSH and requests a remote conductor from iTerm2. buildssh constructs the distributable SSH utility, bash-minify removes blank and comment lines, and Makefile copies the built utility into an external resources directory.
Observed
- License
- GNU General Public License version 2
- Implementation languages
- Bash, Python, and Perl
- Interface
- Command-line utilities using iTerm2 OSC 1337 control sequences
- Remote interface
- SSH wrapper plus a Unix-domain-socket proxy client
- Python requirements
- Remote proxy requires Python 3.7+ and only the standard library; API utility requires the external iterm2 module
- Packaging surface
- Make targets copy the built SSH utility into an external resources directory
- Terminal multiplexer handling
- Image, text, upload, and download utilities wrap control sequences for tmux or screen-style terminals
Read from README.md, Makefile, shell_integration/it2.py, LICENSE, buildssh, bash-minify, utilities/imgls, utilities/it2dl, utilities/it2ul, utilities/imgcat, utilities/it2api, utilities/it2cat, utilities/it2git, utilities/it2ssh, utilities/it2tip.
What it can do
Display inline images in terminal
Image files → Rendered images within terminal interface
Mark command boundaries
Terminal commands → Visual markers separating command blocks
Transfer files to/from terminal
Local or remote files → Files copied between locations
Track command history with metadata
Executed shell commands → Enhanced command history with timestamps and context
Enable shell prompt customization
Shell configuration → Enhanced terminal prompt with additional information
Integrate with iTerm2 features
Shell session data → Enhanced terminal functionality and user experience
Tags
Tech Stack
Comments (0)
No comments yet
Editorially curated, with community endorsements as a secondary signal. Corrections welcome.