iterm2 — Claude Code skill: features and installation
This skill helps an agent work with iTerm2 and tmux, from split panes to persistent sessions. Use it for terminal setup and troubleshooting on macOS.
MIT 115 installs ★ 17 updated 2026-10-14
npx skills add julianobarbosa/claude-code-skills --skill iterm2 -a claude-codeWhat iterm2 does
The skill covers iTerm2 shortcuts, tmux configuration, and the tmux -CC integration mode. It can guide an agent through splitting panes, reconnecting to a session after an SSH disconnect, or using tmux windows as native iTerm2 windows. Reference material covers shortcuts, tmux configuration, and commands.
There are workflows for setup, session management, and troubleshooting. When a workflow runs, the skill calls a notification script and tells the user which workflow is underway. The tmux -CC mode needs an installed, running tmux server. For a remote host, start SSH from iTerm2 itself.
Some behavior depends on the active profile and pane. For instance, Cmd+D uses the current pane’s profile rather than the window default, so a new pane can inherit changed environment variables or PATH. That can affect commands in the new pane.
What it helps with
- split an iTerm2 window into vertical or horizontal panes
- configure tmux windows to work with iTerm2
- create a named tmux session and reconnect after an SSH disconnect
- find an iTerm2 shortcut or tmux command
- troubleshoot unexpected tmux or shell behavior
Example prompts for the agent
- Show me how to split an iTerm2 terminal into panes and move between them.
- Set up
tmux -CCso tmux windows appear as iTerm2 windows. - Create a named tmux session that stays available after SSH disconnects, then show me how to reconnect.
How to install iterm2
1Skills CLI (Vercel)
npx skills add julianobarbosa/claude-code-skills --skill iterm2 -a claude-code2Manually: put the files in place
~/.claude/skills/iterm2/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/iterm2/
1Skills CLI (Vercel)
npx skills add julianobarbosa/claude-code-skills --skill iterm2 -a codex2Manually: put the files in place
.agents/skills/iterm2/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add julianobarbosa/claude-code-skills --skill iterm2 -a cursor2Manually: put the files in place
.cursor/skills/iterm2/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install julianobarbosa/claude-code-skills skills/iterm22Manually: put the files in place
.github/skills/iterm2/SKILL.md1Skills CLI (Vercel)
npx skills add julianobarbosa/claude-code-skills --skill iterm2 -a gemini-cli2Platform CLI
gemini skills install https://github.com/julianobarbosa/claude-code-skills --path skills/iterm2Manually: put the files in place
.devin/skills/iterm2/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add julianobarbosa/claude-code-skills --skill iterm2 -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about iterm2
How do I install iterm2 in Claude Code?
Run npx skills add julianobarbosa/claude-code-skills --skill iterm2 -a claude-code. The skill file is at ~/.claude/skills/iterm2/SKILL.md.
What does the iterm2 skill do?
It gives an agent references and workflows for iTerm2 and tmux, including shortcuts, pane management, setup, and session recovery.
What does tmux -CC require?
The tmux server must be installed and running. To reach a remote tmux server, launch SSH from iTerm2 rather than from a script that starts a subshell.
Source text
SKILL.md · MIT
---
name: iterm2
description: iTerm2 terminal emulator and tmux multiplexer expertise. USE WHEN user mentions iTerm2, tmux, terminal sessions, split panes, window management, OR terminal productivity on macOS.
---
# Iterm2
Complete reference for iTerm2 terminal emulator and tmux terminal multiplexer on macOS. Covers keyboard shortcuts, configuration, tmux integration, and productivity workflows.
## Workflow Routing
**When executing a workflow, do BOTH of these:**
1. **Call the notification script** (for observability tracking):
```bash
~/.claude/Tools/SkillWorkflowNotification WORKFLOWNAME Iterm2
```
2. **Output the text notification** (for user visibility):
```
Running the **WorkflowName** workflow from the **Iterm2** skill...
```
| Workflow | Trigger | File |
|----------|---------|------|
| **SetupTmux** | "setup tmux", "configure tmux" | `workflows/SetupTmux.md` |
| **TmuxSession** | "tmux session", "attach session", "detach" | `workflows/TmuxSession.md` |
| **TroubleshootTmux** | "tmux not working", "fix tmux" | `workflows/TroubleshootTmux.md` |
## Examples
**Example 1: Split terminal into multiple panes**
```
User: "How do I split my terminal in iTerm2?"
→ References Shortcuts.md
→ Explains Cmd+D (vertical) and Cmd+Shift+D (horizontal)
→ Shows navigation with Cmd+Option+Arrow
```
**Example 2: Setup tmux with iTerm2 integration**
```
User: "How do I use tmux with iTerm2?"
→ Invokes SetupTmux workflow
→ Explains tmux -CC control mode
→ Shows native window integration benefits
```
**Example 3: Manage persistent sessions over SSH**
```
User: "Keep my terminal running after disconnect"
→ Invokes TmuxSession workflow
→ Creates named session with tmux new -s
→ Shows how to reattach after disconnect
```
## Quick Reference
### iTerm2 Essentials
| Action | Shortcut |
|--------|----------|
| Split Vertical | `Cmd+D` |
| Split Horizontal | `Cmd+Shift+D` |
| Navigate Panes | `Cmd+Option+Arrow` |
| Maximize Pane | `Cmd+Shift+Enter` |
| Next/Prev Tab | `Cmd+{` / `Cmd+}` |
| Find | `Cmd+F` |
| Autocomplete | `Cmd+;` |
| Paste History | `Cmd+Shift+H` |
| Instant Replay | `Cmd+Option+B` |
| Find Cursor | `Cmd+/` |
### tmux Essentials
Default prefix: `Ctrl+b`
| Action | Shortcut |
|--------|----------|
| New Session | `tmux new -s name` |
| List Sessions | `tmux ls` or `Ctrl+b s` |
| Attach Session | `tmux attach -t name` |
| Detach | `Ctrl+b d` |
| New Window | `Ctrl+b c` |
| Split Vertical | `Ctrl+b %` |
| Split Horizontal | `Ctrl+b "` |
| Navigate Panes | `Ctrl+b Arrow` |
| Zoom Pane | `Ctrl+b z` |
| Close Pane | `Ctrl+b x` |
| Copy Mode | `Ctrl+b [` |
### iTerm2 + tmux Integration
Run `tmux -CC` for native iTerm2 integration:
- tmux windows appear as native iTerm2 windows
- Use iTerm2 shortcuts instead of tmux prefix
- Sessions persist through disconnects
- Dashboard available via Shell > tmux > Dashboard
## Documentation Index
| Document | Purpose |
|----------|---------|
| `Shortcuts.md` | Complete keyboard shortcut reference |
| `TmuxConfig.md` | tmux configuration (.tmux.conf) guide |
| `TmuxCommands.md` | Full tmux command reference |
---
## Gotchas
- **"Reuse previous session's directory" is per-profile and per-context:** New windows from Cmd-N use the profile's window setting; new tabs from Cmd-T use the tab setting. They differ — confusing when prompts open in unexpected directories.
- **`tmux -CC` requires the tmux server to be installed and started:** If tmux is on a remote host but iTerm2 is local, `tmux -CC attach` works over SSH only when SSH was started from iTerm2 itself — not from a script that spawns a subshell.
- **Cmd-D split uses the current pane's profile, NOT the window default:** Once a profile changes mid-session (via shell integration), new splits inherit the modified profile and can carry unwanted env or PATH.
- **`Ctrl+b` prefix conflicts with readline `transpose-words`:** Vi-mode users who rebind it (`set -g prefix C-a`) must remember `Ctrl+a` also conflicts with screen and shell line-start — pick a free combo like `C-Space`.
- **Shell integration injects OSC 1337 escape codes:** Pipelines that capture terminal output (script, asciinema) end up with garbled control sequences unless integration is disabled per-pane via `Edit Session > Disable Shell Integration`.
- **Status bar updates run on the main thread:** Heavy custom status bar scripts (long `git status`, slow cloud CLIs) freeze the entire terminal — keep status callbacks under 100ms or run them async.
© julianobarbosa · MIT · julianobarbosa/claude-code-skills