show-me

Files (6)

• SKILL.md
• commands.md · references/
• layouts.md · references/
• troubleshooting.md · references/
• walkthrough.md · references/
• show-me · scripts/

SKILL.md (first lines)

# 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

From mbailey/show-me, MIT.

More from mbailey/show-me