show-me

# 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](references/walkthrough.md) - 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 ```bash 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: ```bash 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: ```bash 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 ```bash 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](references/commands.md) - Full command reference - [Layouts](references/layouts.md) - Layout options and `SHOW_LAYOUT` - [Guided Voice Walkthroughs](references/walkthrough.md) - Voice show-and-tell: the highlight-then-narrate loop, walkthrough etiquette, prepared tours - [Troubleshooting](references/troubleshooting.md) - 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 ```bash # 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