show-me

name	show-me
description	Visual context sharing. LOAD when user says "show me", "open in browser", or "look at".

show-me

Display content for users (files, URLs, commands) or observe their screen context.

The plugin ships two top-level commands:

• show-me — display content for the user (files in Neovim, URLs in a browser, commands in a tmux pane)
• look-at — observe what the user is currently viewing (screen context, active panes)

Quick Reference

Command	Example	Description
show-me <file>	show-me README.md:42	Open file in Neovim at line
show-me <file>	show-me main.py:10-20	Open file highlighting line range
show-me <file>.html	show-me index.html	Open in browser (rendered) — use --editor for the source
show-me <url>	show-me github.com	Open URL in browser
show-me "cmd:..."	show-me "cmd:git log"	Run command in shell pane
show-me pane:self	show-me pane:self	Agent self-focus — pull the user's focus to your own pane ("show yourself" / "where are you"). Uses $TMUX_PANE
look-at	look-at -l 100	Capture pane with last 100 lines of scrollback
look-at -H	look-at -H	Show tmux hierarchy only

When to Use

• User asks to open/display a file or URL (For URLs: ALWAYS check Chrome MCP first)
• User says "show me" or "look at my screen"
• User says "show yourself" / "where are you" / "I can't find you" (agent self-focus) → show-me pane:self
• Working in voice mode (hands-free interaction) — highlight first, then narrate the range you showed; see Guided Voice Walkthroughs
• Need to verify what user is viewing

Showing URLs - Default Behavior

URLs go to Chrome MCP by default. The show-me command is a fallback.

URL Navigation Decision Tree

User requests URL
    ↓
Check Chrome MCP available?
    ├─ Yes → navigate tool (interactive)
    └─ No  → show-me command (fallback)

Standard Workflow

1. Check: mcp__claude-in-chrome__tabs_context_mcp(createIfEmpty=true)
2. If available:
   • Inform user: "Opening in Chrome - you may need to approve domain permissions"
   • Use tabs_create_mcp + navigate tools for interactive control
   • On timeout: "Chrome may be waiting for permission approval. Open in default browser instead?"
3. If unavailable: Use show-me command (opens default browser)

Chrome MCP provides:

• Interactive control (scroll, click, fill forms)
• Screenshots and page inspection
• Better for demos and automation

The show-me command is a fallback for when Chrome MCP is unavailable.

Prefer Line Ranges Over Single Lines

When showing code to the user, prefer ranges (file:start-end) over single lines (file:line).

A single line rarely provides enough context. When pointing out a function, a bug, a block of logic, or a diff location, show the full range so the user sees the complete picture.

Instead of	Use
show-me main.py:42	show-me main.py:38-55 (show the whole function)
show-me config.yaml:10	show-me config.yaml:8-15 (show the relevant block)

Rule of thumb: If you know the start line, find where the section ends and use a range.

Usage

AI assistants: Use bare show-me and look-at -- they're on PATH.

show-me - Display Content

show-me README.md                    # Open file (uses user's default layout)
show-me src/main.py:42               # Open at line 42
show-me src/main.py:10-20            # Open highlighting lines 10-20 (preferred)
show-me bin/show-me#L124-162         # Highlight function (URL fragment syntax)
show-me index.html                   # HTML opens in the browser (rendered), not Neovim
show-me --editor index.html          # Escape hatch: open the HTML source in Neovim
show-me https://github.com/repo      # Open URL
show-me "cmd:git status"             # Run command
show-me pane:15                      # Focus pane
show-me --hold 60 README.md          # Hold focus for 60s (visual conch)
show-me --layout right README.md     # Open in split pane to the right
show-me --here "cmd:make test"       # Split pane (default direction for type)
show-me --cwd /path/to/repo "cmd:make test"  # Run cmd: in a specific directory
show-me --format json "cmd:make"     # Run command, get a machine handle back

--cwd PATH runs a cmd: target in PATH instead of the caller's cwd (wrapped as cd -- "<PATH>" && <cmd>). No-op for file/URL targets. A missing directory is a hard error (show-me: --cwd: no such directory: <PATH>, no pane created) — show-me never silently falls back to the caller's cwd.

Layout: You don't need to specify --layout — just call show-me <target>. The user's SHOW_LAYOUT env var controls where content appears. In split mode, subsequent file shows reuse the existing Neovim pane.

Following up on a cmd: you ran. The default human line ends with [pane %NN]; --format json returns a one-line handle so you can inspect the result instead of guessing:

show-me --format json "cmd:make test"
# {"pane":"%37","session":"main","window":"build","created":true,"status":"alive","cmd":"make test"}
tmux capture-pane -p -t %37        # read the output

Prefer --format json over scraping prose. Fields: pane (handle for tmux capture-pane/send-keys), session/window (full names), created (new vs reused), status (alive/exited:<code>/unknown), cmd. See references/commands.md for the full reference.

File Syntax Variants

All four forms are supported for specifying lines:

show-me file:line                    # Single line
show-me file:start-end               # Line range (preferred)
show-me file#Lline                   # URL fragment style
show-me file#Lstart-end              # URL fragment range

look-at - Observe Context

look-at                              # Current pane
look-at -l 100                       # Last 100 lines
look-at -H                           # Hierarchy only
look-at %15,%16                      # Multiple panes
look-at window                       # All panes in window

Documentation

• Commands - Full command reference
• Layouts - Layout options and SHOW_LAYOUT
• Guided Voice Walkthroughs - Voice show-and-tell: the highlight-then-narrate loop, walkthrough etiquette, prepared tours
• Troubleshooting - Common issues

Chrome Browser Integration (Reference)

This section provides additional details on Chrome MCP integration. See "Showing URLs - Default Behavior" above for the primary workflow.

Chrome Domain Permissions

Chrome requires user approval for new domains (security feature).

Best practices:

• Before navigating: Inform user they may need to approve domain permissions
• On timeout: Explain likely cause - "Chrome may be waiting for permission approval"
• Offer fallback: "Would you like me to open in default browser instead?"

Common issue: If navigation times out, it's usually because the user didn't see or approve the Chrome domain permission prompt.

Example: Show URL with Chrome MCP

# Step 1: Check if Chrome MCP is connected
# Call: mcp__claude-in-chrome__tabs_context_mcp(createIfEmpty=true)

# Step 2: If connected, inform user and navigate
# "Opening in Chrome - you may need to approve domain permissions"
# Call: mcp__claude-in-chrome__tabs_create_mcp (get a new tab)
# Call: mcp__claude-in-chrome__navigate with the URL and tabId

# Step 3: If not connected or timeout, fall back to show-me command
show-me https://example.com

Troubleshooting Chrome MCP

Issue	Solution
tabs_context_mcp fails	Chrome extension not connected; use show-me command
Tab ID invalid	Call tabs_context_mcp to get fresh tab IDs
Extension disconnected mid-session	Graceful fallback to show-me command
No Chrome MCP tools available	MCP not configured; use show-me command

Setup

To use Chrome MCP:

1. Install the Claude-in-Chrome browser extension
2. Open Chrome and click the Claude extension icon
3. The extension connects to Claude Code via MCP

When the extension is not connected, tabs_context_mcp will fail, and you should fall back to the standard show-me command.

Requirements

• tmux: Required for pane management
• Neovim: For file display (with socket support)
• Browser: For URL display (Firefox preferred, Chrome with MCP preferred for interactive control)
• nvim-remote: Optional, enhances Neovim integration