iterm2

Q: How do I install iterm2?

Run npx skills add https://github.com/julianobarbosa/claude-code-skills --skill iterm2 in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/iterm2/ (personal) or .claude/skills/iterm2/ (project).

by julianobarbosaProductivity & Automation

iTerm2 terminal emulator and tmux multiplexer expertise. USE WHEN user mentions iTerm2, tmux, terminal sessions, split panes, window management, OR terminal productivity on macOS.

Installs: 114
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/julianobarbosa/claude-code-skills --skill iterm2

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads iterm2 automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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:

Call the notification script (for observability tracking):

~/.claude/Tools/SkillWorkflowNotification WORKFLOWNAME Iterm2

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.

FAQ

What does the iterm2 skill do?

iTerm2 terminal emulator and tmux multiplexer expertise. USE WHEN user mentions iTerm2, tmux, terminal sessions, split panes, window management, OR terminal productivity on macOS.

How do I install iterm2?

Run npx skills add https://github.com/julianobarbosa/claude-code-skills --skill iterm2 in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/iterm2/ (personal) or .claude/skills/iterm2/ (project).

Which AI agents can use iterm2?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is iterm2 safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains iterm2?

It is published by julianobarbosa in julianobarbosa/claude-code-skills. It has 114 recorded installs.