home / skills / julianobarbosa / claude-code-skills / iterm2-skill

iterm2-skill skill

safe

This skill helps you master iTerm2 and tmux on macOS, boosting terminal productivity with pane management, session persistence, and native integration.

npx playbooks add skill julianobarbosa/claude-code-skills --skill iterm2-skill

Review the files below or copy the command above to add this skill to your agents.

Files (8)

SKILL.md

3.1 KB

---
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 |

Overview

This skill provides practical expertise for iTerm2 terminal emulator and tmux multiplexer on macOS. It condenses keyboard shortcuts, configuration tips, tmux integration steps, and productivity workflows to speed up terminal work. Use it to optimize pane/window workflows, set up persistent sessions, and troubleshoot tmux integration with iTerm2.

How this skill works

The skill inspects user intent for iTerm2, tmux, terminal sessions, split panes, window management, or macOS terminal productivity and returns targeted guidance. For workflow execution it emits a short notification for observability and prints a user-visible status line indicating which workflow is running. It provides concrete commands, keyboard shortcuts, and step-by-step actions for setup, session management, and troubleshooting.

When to use it

You want to split and navigate panes in iTerm2 efficiently
You need to set up tmux to persist sessions across SSH disconnects
You want native iTerm2 <-> tmux integration (tmux -CC)
You need quick troubleshooting for tmux or session reattachment
You want a compact reference of iTerm2 and tmux shortcuts

Best practices

Use iTerm2 shortcuts (Cmd+D, Cmd+Shift+D, Cmd+Option+Arrow) to manage panes quickly
Run tmux with control mode (tmux -CC) to let iTerm2 manage tmux windows natively
Create named tmux sessions (tmux new -s name) for predictable reattachment
Keep a small .tmux.conf with sensible defaults for splits, copy mode, and prefix remapping
Detach with Ctrl+b d before disconnecting and reattach with tmux attach -t name

Example use cases

Split a terminal vertically (Cmd+D) and horizontally (Cmd+Shift+D) and navigate with Cmd+Option+Arrow
Set up tmux integration: configure tmux, start with tmux -CC, then use iTerm2 windows as tmux windows
Create persistent remote session: ssh -> tmux new -s work -> disconnect -> reattach with tmux attach -t work
Troubleshoot a non-responsive tmux: check tmux ls, kill/stale sessions, and verify .tmux.conf syntax
Maximize a frequently used pane (Cmd+Shift+Enter) for focused work and restore layout afterward

FAQ

How do I keep processes running after I disconnect from SSH?

Start a named tmux session (tmux new -s name) and detach with Ctrl+b d before disconnecting; reattach later with tmux attach -t name.

How do I integrate tmux with iTerm2 so tmux windows look native?

Run tmux in control mode using tmux -CC. iTerm2 will show tmux windows as native windows and you can use iTerm2 shortcuts for window management.