Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add julianobarbosa/claude-code-skills --skill iterm2 -a claude-code
Open on GitHub

What 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 -CC so 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-code

2Manually: put the files in place

~/.claude/skills/iterm2/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/iterm2/

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

Similar skills

All skills for DevOps and infrastructure →

From the same set37

The whole set →
mimir Teaches the agent how to stand up Grafana Mimir on Kubernetes and wire S3, GCS or Azure Blob for long-term Prometheus metric retention. CX Codex +1 118installs obsidian-nvim Guides AI agents through configuring obsidian.nvim in Neovim, covering vaults, templates, daily notes, and picker integrations. CX Codex +1 116installs repomix repomix packs a repository into one file an LLM can read, with path filters, signature compression and token counts. Useful before a review or when code has to fit a context window. CX Codex +1 115installs managing-infra managing-infra guides Kubernetes architectural choices, Terraform module structuring, Helm usage, and GitHub Actions CI/CD workflows. CX Codex +1 115installs context7 Look up version-specific library documentation and code examples through Context7. Use it before coding against an API or framework behavior you’re unsure about. CX Codex +1 114installs git-worktree Automates git worktree workflows with tmux windows and iTerm2 tabs. Helps run isolated feature branches and parallel Claude Code sessions. CX Codex +1 111installs writing-typescript writing-typescript — a TypeScript skill for Node.js services, React apps, and TS pattern discussions. It favors strict typing, composition, and a toolchain built around bun and vite. CX Codex +1 111installs az-aks-agent az-aks-agent is a Claude Code skill that investigates Azure Kubernetes Service cluster health and configuration. It examines pod, networking, storage, and RBAC issues. CX Codex +1 110installs

Project sponsors

Companies that keep this analytics open