Run any Skill in Manus with one click

amvcp-iterm2-preview

Stars0

Forks0

UpdatedMay 25, 2026 at 00:59

Preview an HTML page or render a Mermaid diagram as SVG inside an iTerm2 vertical split-pane (Web Browser profile) right next to the terminal. Aborts cleanly on any non-iTerm2 host (Claude Desktop, Terminal.app, VS Code, tmux, SSH, web shells). Use when the user wants to preview an HTML file or see a Mermaid diagram rendered without leaving the terminal. Trigger with 'show me a preview', 'preview the HTML', 'render this as SVG'.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

Emasoft

Emasoft/ai-maestro-visual-communicator-plugin

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

File Explorer

8 files

SKILL.md

readonly

name	amvcp-iterm2-preview
description	Preview an HTML page or render a Mermaid diagram as SVG inside an iTerm2 vertical split-pane (Web Browser profile) right next to the terminal. Aborts cleanly on any non-iTerm2 host (Claude Desktop, Terminal.app, VS Code, tmux, SSH, web shells). Use when the user wants to preview an HTML file or see a Mermaid diagram rendered without leaving the terminal. Trigger with 'show me a preview', 'preview the HTML', 'render this as SVG'.
license	MIT
compatibility	macOS only. Real iTerm2.app + 'Web Browser' profile required. Mermaid mode also needs `mmdc`.
metadata	{"author":"Emasoft"}

iTerm2 Preview

Overview

Splits the current iTerm2 tab vertically and opens an HTML/SVG file in the right-hand pane via a "Web Browser" profile. Refuses on every non-iTerm2 host (Claude Desktop, Terminal.app, WezTerm/Alacritty/Kitty, VS Code, Cursor, tmux/screen, SSH, Codespaces/Gitpod/Replit/Jupyter/xterm.js) — Step 0 aborts cleanly.

Auto-invoked by scripts/amvcp-select.py: opens generated pages in a split-pane instead of Chrome on iTerm2; otherwise existing browser flow runs unchanged. Opt-out via VE_SELECT_NO_ITERM=1.

Prerequisites

macOS with iTerm2.app installed and currently running.
iTerm2 profile named exactly "Web Browser" (Preferences → Profiles → "+" → set as browser session).
osascript available (default on macOS).
For Mermaid mode: mmdc (npm i -g @mermaid-js/mermaid-cli).
NOT inside tmux/screen, SSH, VS Code, Cursor, or a web-hosted shell.

Instructions

Step 0 — verify host is real iTerm2. ALWAYS run before any AppleScript:
```
uv run "$CLAUDE_PLUGIN_ROOT/skills/amvcp-iterm2-preview/scripts/detect_iterm2.py"
```
On non-zero exit, abort with the stderr message verbatim. Do NOT bypass.
Locate the file. HTML: use the user's path or find . -name "*.html" | head. Mermaid: see cookbook for the mmdc + svg_to_html.py wrap chain.
Open the split-pane: osascript ".../scripts/open_preview.applescript" "<url>" where <url> is complete (file://<abs-path> or http://localhost:<port>/...).
Tell the user how to close: "Preview open in the right pane. Close with osascript .../scripts/close_preview.applescript or exit inside that pane."

Output

Vertical split-pane in the current iTerm2 tab, right ~50%, "Web Browser" profile pointing at the URL. Terminal session preserved on the left. Mermaid mode writes to /tmp.

Side effects: disables iTerm2 pane dimming globally + names the preview pane "amvcp Preview" + tints its tab color bright gray (#D0D0D0) for visual distinction. Enable Settings → Profiles → Web Browser → "Show Title Bar" to see both cues. See cookbook for details.

Error Handling

Symptom	Fix
`NOT-iTerm2: …` from Step 0	stderr names which check failed. Do NOT bypass.
`"Web Browser" profile not found`	Create in Preferences → Profiles → "+".
`mmdc: command not found`	`npm i -g @mermaid-js/mermaid-cli`.
Pane blank	URL must be complete; use `$(realpath ...)` for files.
Wrong window	AppleScript uses `current window`; bring target to front.

Examples

Input: "show me the landing page".

$ uv run ".../detect_iterm2.py"
iTerm2 verified: TERM_PROGRAM=iTerm.app, LC_TERMINAL=iTerm2, …
$ osascript ".../open_preview.applescript" "file://$(realpath ./index.html)"

Output: "Preview open in the right pane. Close with the close_preview.applescript when done."

Negative example: Codespaces. Step 0 returns NOT-iTerm2: web/cloud terminal detected: GitHub Codespaces ($CODESPACES is set). Abort; suggest /amvcp-share-page instead.

Modes

Not applicable — this skill is a terminal/iTerm pane lifecycle helper, not a render skill. It does NOT emit DOM or carry a data-ve-mode attribute (R20-R23 of amvcp-self-debug-rules don't apply).

Composability

Not applicable in the visual sense — iTerm pane management is orthogonal to the visual rendering skills. Multiple amvcp-iterm2-preview invocations from the same shell are guarded by the safeguard in open_preview.applescript (R7).

Resources

iterm2-preview-cookbook.md — detector internals, Mermaid workflow, abort cases.

Why detect iTerm2 first · Detector internals · Mode 1 — HTML preview workflow · Mode 2 — Mermaid → SVG workflow · Worked examples · Closing the preview · Side effects of opening a preview · Page navigation — Python API + keystroke fallback · Recommended one-time profile setup · Why focused/unfocused title bars sometimes look the same · close_preview.applescript safety
- Why detect iTerm2 first
- Detector internals
- Mode 1 — HTML preview workflow
- Mode 2 — Mermaid → SVG workflow
- Worked examples
- Closing the preview

More from this repository

same repository

amvcp-anim-sandbox

Emasoft/ai-maestro-visual-communicator-plugin

Animation sandbox — ONE transition shown in isolation with live duration + easing tuners, a Replay button, and an export of the tuned {duration, easing} values. Moving the slider or easing select re-runs the transition live; the tuned values export through the runtime selection channel. Light + dark, reduced-motion-aware. Use when tuning a transition, dialling in animation timing, picking an easing curve, or building an easing/duration playground. Trigger with 'animation sandbox', 'tune a transition', 'easing tuner', 'duration slider', 'easing playground', 'pick an easing curve'.

2026-06-200

amvcp-code-diff

Emasoft/ai-maestro-visual-communicator-plugin

Code diff surface — unified + split diff blocks, twin-column gutter, semantic diff tints, PR review pages with line-anchored comments. Use when scaffolding a code diff, a side-by-side review, a PR / postmortem / changelog page. Trigger with 'diff', 'split diff', 'unified diff', 'PR review', 'code review', 'pull request', 'postmortem', 'hunk', 'line-diff'.

2026-06-200

amvcp-code-fences

Emasoft/ai-maestro-visual-communicator-plugin

Code-as-data and editable-fence surface — distinguishes pre tag as code vs data (CSV/JSON/YAML), the data-ve-no-gutter opt-out, and the contenteditable code-editor family. Use when scaffolding a CSV/JSON data block, a live editor, an opt-out gutter block, or deciding fenced vs free-form. Trigger with 'CSV', 'JSON data', 'YAML data', 'data fence', 'opt-out gutter', 'contenteditable', 'JSON editor', 'live edit code', 'no-gutter'.

2026-06-200

amvcp-code-highlight

Emasoft/ai-maestro-visual-communicator-plugin

Router skill for the code-display surface — dispatches to 4 sibling skills: code-syntax, code-diff, code-snippets, code-fences. Use when scaffolding ANY code-display surface and you don't yet know which sub-surface fits. Trigger with 'code', 'code block', 'syntax highlight', 'diff', 'PR review', 'walkthrough', 'tabbed code', 'CSV data', 'JSON editor'.

2026-06-200

amvcp-code-snippets

Emasoft/ai-maestro-visual-communicator-plugin

Multi-perspective code composition surface — collapsed walkthroughs, snippet-on-hover, tabbed multi-perspective panels, click-step-to-code, N-column compare layouts. Use when scaffolding a code walkthrough, explainer, tutorial, or click-driven code reveal. Trigger with 'walkthrough', 'tabbed code', 'click reveal code', 'snippet', 'explainer', 'tutorial steps', 'compare approaches'.

2026-06-200

amvcp-code-syntax-chrome

Emasoft/ai-maestro-visual-communicator-plugin

Visual chrome + inline hand-wrap for code blocks — block 3-state hover/select model, blueprint theme, slate-bg panel, file-path / tab-bar headers, inline code chip, 4-class hand-wrap palette, keyword-arrow highlight, plus the author-vs-runtime + light/dark cross-cutting discipline. Use when styling a code block's container, adding a file-path or tab-bar header, hand-wrapping inline code without the JS tokenizer, or wiring light/dark token mirrors. Trigger with 'block hover state', 'blueprint theme', 'slate panel', 'file-path header', 'tab-bar', 'inline code chip', 'hand-wrap', 'keyword highlight', 'light dark code mirror', 'author vs runtime'.

2026-06-200

name	amvcp-iterm2-preview
description	Preview an HTML page or render a Mermaid diagram as SVG inside an iTerm2 vertical split-pane (Web Browser profile) right next to the terminal. Aborts cleanly on any non-iTerm2 host (Claude Desktop, Terminal.app, VS Code, tmux, SSH, web shells). Use when the user wants to preview an HTML file or see a Mermaid diagram rendered without leaving the terminal. Trigger with 'show me a preview', 'preview the HTML', 'render this as SVG'.
license	MIT
compatibility	macOS only. Real iTerm2.app + 'Web Browser' profile required. Mermaid mode also needs `mmdc`.
metadata	{"author":"Emasoft"}

iTerm2 Preview

Overview

Auto-invoked by scripts/amvcp-select.py: opens generated pages in a split-pane instead of Chrome on iTerm2; otherwise existing browser flow runs unchanged. Opt-out via VE_SELECT_NO_ITERM=1.

Prerequisites

macOS with iTerm2.app installed and currently running.
iTerm2 profile named exactly "Web Browser" (Preferences → Profiles → "+" → set as browser session).
osascript available (default on macOS).
For Mermaid mode: mmdc (npm i -g @mermaid-js/mermaid-cli).
NOT inside tmux/screen, SSH, VS Code, Cursor, or a web-hosted shell.

Instructions

Step 0 — verify host is real iTerm2. ALWAYS run before any AppleScript:
```
uv run "$CLAUDE_PLUGIN_ROOT/skills/amvcp-iterm2-preview/scripts/detect_iterm2.py"
```
On non-zero exit, abort with the stderr message verbatim. Do NOT bypass.
Locate the file. HTML: use the user's path or find . -name "*.html" | head. Mermaid: see cookbook for the mmdc + svg_to_html.py wrap chain.
Open the split-pane: osascript ".../scripts/open_preview.applescript" "<url>" where <url> is complete (file://<abs-path> or http://localhost:<port>/...).
Tell the user how to close: "Preview open in the right pane. Close with osascript .../scripts/close_preview.applescript or exit inside that pane."

Output

Vertical split-pane in the current iTerm2 tab, right ~50%, "Web Browser" profile pointing at the URL. Terminal session preserved on the left. Mermaid mode writes to /tmp.

Error Handling

Symptom	Fix
`NOT-iTerm2: …` from Step 0	stderr names which check failed. Do NOT bypass.
`"Web Browser" profile not found`	Create in Preferences → Profiles → "+".
`mmdc: command not found`	`npm i -g @mermaid-js/mermaid-cli`.
Pane blank	URL must be complete; use `$(realpath ...)` for files.
Wrong window	AppleScript uses `current window`; bring target to front.

Examples

Input: "show me the landing page".

$ uv run ".../detect_iterm2.py"
iTerm2 verified: TERM_PROGRAM=iTerm.app, LC_TERMINAL=iTerm2, …
$ osascript ".../open_preview.applescript" "file://$(realpath ./index.html)"

Output: "Preview open in the right pane. Close with the close_preview.applescript when done."

Negative example: Codespaces. Step 0 returns NOT-iTerm2: web/cloud terminal detected: GitHub Codespaces ($CODESPACES is set). Abort; suggest /amvcp-share-page instead.

Modes

Composability

Resources

iterm2-preview-cookbook.md — detector internals, Mermaid workflow, abort cases.

Why detect iTerm2 first · Detector internals · Mode 1 — HTML preview workflow · Mode 2 — Mermaid → SVG workflow · Worked examples · Closing the preview · Side effects of opening a preview · Page navigation — Python API + keystroke fallback · Recommended one-time profile setup · Why focused/unfocused title bars sometimes look the same · close_preview.applescript safety
- Why detect iTerm2 first
- Detector internals
- Mode 1 — HTML preview workflow
- Mode 2 — Mermaid → SVG workflow
- Worked examples
- Closing the preview