How do I install the Iterm Workspace skill?

Run npx skillmds@latest add antonio-mello-ai/iterm-workspace in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Iterm Workspace safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Iterm Workspace?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Iterm Workspace free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Iterm Workspace?

antonio-mello-ai (@antonio-mello-ai) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Iterm Workspace by antonio-mello-ai

Name: Iterm Workspace
Rating: 4.2 (5 reviews)
Author: antonio-mello-ai

Iterm Workspace

Scope iTerm automation to the caller tab and pane. Use when working in iTerm and the task involves the current tab, caller pane, non-disruptive splits, preserving focus, routing commands to the right pane, or avoiding interference with another visible iTerm pane.

File contents

iTerm Workspace

Use this skill to keep iTerm automation scoped to the pane and tab that invoked the agent. iTerm does not provide a cmux-style workspace API, so the practical workspace unit is the current iTerm tab.

Default Rule

Anchor on the caller pane first. If the agent process has no TTY, use the current iTerm session as a fallback and say so before making visible changes.

iterm-control identify
iterm-control list

identify reports:

caller_tty: local terminal TTY if available.
resolved_caller.resolution: caller-tty, caller-fallback-current, or another explicit resolution.
current: iTerm's current session.

Non-Disruptive Layout

Build layout additively from the caller/current pane. Prefer commands that create the pane already running the intended command:

iterm-control split --target caller --direction right --command "zsh -lc 'cd /repo && exec codex'"
iterm-control grid --target caller --rows 2 --cols 2 --command "zsh -lc 'cd /repo && exec codex'"

Avoid focus-changing AppleScript unless the user explicitly asks to move focus. When a target is ambiguous, stop and ask for the pane/session id or use a badge or screenshot to verify.

Safe Pane Routing

Use this order for target selection:

session:<id> from a fresh list or identify.
tty:<path> from a fresh list or identify.
caller when identify resolved by caller-tty.
current only when the task is explicitly about the currently focused iTerm pane.

Do not send commands to another pane just because it is visually near the caller. iTerm pane geometry is not exposed reliably through AppleScript.

Rules

Scope actions to the current iTerm tab unless the user asked for another window or tab.
Treat caller-fallback-current as focus-based and user-visible.
Prefer badges and screenshots for confirmation instead of changing focus.
Do not close sessions, tabs, or windows from this skill unless the user explicitly asks.
Do not assume a command launched successfully; validate with list, screenshot, or visible output.

Reference

references/targeting.md gives the target model and failure modes.

---name: iterm-workspacedescription: Scope iTerm automation to the caller tab and pane. Use when working in iTerm and the task involves the current tab, caller pane, non-disruptive splits, preserving focus, routing commands to the right pane, or avoiding interference with another visible iTerm pane.---# iTerm WorkspaceUse this skill to keep iTerm automation scoped to the pane and tab that invokedthe agent. iTerm does not provide a cmux-style workspace API, so the practicalworkspace unit is the current iTerm tab.## Default RuleAnchor on the caller pane first. If the agent process has no TTY, use the currentiTerm session as a fallback and say so before making visible changes.```bashiterm-control identifyiterm-control list````identify` reports:- `caller_tty`: local terminal TTY if available.- `resolved_caller.resolution`: `caller-tty`, `caller-fallback-current`, or another explicit resolution.- `current`: iTerm's current session.## Non-Disruptive LayoutBuild layout additively from the caller/current pane. Prefer commands that createthe pane already running the intended command:```bashiterm-control split --target caller --direction right --command "zsh -lc 'cd /repo && exec codex'"iterm-control grid --target caller --rows 2 --cols 2 --command "zsh -lc 'cd /repo && exec codex'"```Avoid focus-changing AppleScript unless the user explicitly asks to move focus.When a target is ambiguous, stop and ask for the pane/session id or use a badgeor screenshot to verify.## Safe Pane RoutingUse this order for target selection:1. `session:<id>` from a fresh `list` or `identify`.2. `tty:<path>` from a fresh `list` or `identify`.3. `caller` when `identify` resolved by `caller-tty`.4. `current` only when the task is explicitly about the currently focused iTerm pane.Do not send commands to another pane just because it is visually near the caller.iTerm pane geometry is not exposed reliably through AppleScript.## Rules- Scope actions to the current iTerm tab unless the user asked for another window or tab.- Treat `caller-fallback-current` as focus-based and user-visible.- Prefer badges and screenshots for confirmation instead of changing focus.- Do not close sessions, tabs, or windows from this skill unless the user explicitly asks.- Do not assume a command launched successfully; validate with `list`, screenshot, or visible output.## Reference- [references/targeting.md](references/targeting.md) gives the target model and failure modes.

Frequently asked questions