Add cursor-triggered image previews for macOS and Ghostty

[karanb192]

Summary

• Add image-peek for macOS: moving the prompt cursor onto a pasted image marker opens a large dark preview pane; moving away hides it. Request up to about 72% of the window width, adjusted for image proportions. Keep an above-prompt fallback in narrow windows.
• Capture new clipboard images with a bundled macOS helper, keep up to 24 private temporary PNGs per session, preserve previews through hot reload, and clean up at session boundaries. Add /image-peek on|off.
• Add the marketplace entry, plugin README, root README listing and landing-page card. Update the shared installation guidance for mods being enabled by default in Claude Code 2.1.287+.
• Recognize Ghostty, iTerm2 and Herdr. Document the per-launch Claude renderer override needed for experimental iTerm2 and Herdr support, and log setup guidance when it is absent.
• Add 17 native runtime tests, including terminal detection, large-pane sizing, background coverage, focus preservation and the narrow-window fallback.

Details

The prompt API exposes marker text and cursor position but not draft attachment bytes. Capture therefore happens after detecting a new native image marker. Copying a different image before capture can produce the wrong preview; the README asks users to wait for each preview before copying another image. Simultaneous unseen markers fail closed. This first version supports clipboard image paste, not attachment paths or drag-and-drop.

The plugin starts only local processes and makes no model or network calls. Its README includes the validator footprint, cache permissions and limits, and the five-line threat model.

iTerm2 3.7.3+ and local Herdr 0.9.1+ are experimental routes. Their graphics prerequisites and the CLAUDE_CODE_FORCE_TERMINAL_IMAGES=1 launch override are documented; the mod does not change environment variables, terminal settings or the user's theme. End-to-end image pixels in these terminals have not been visually verified.

A user-provided Ghostty screenshot confirms the large image and dark canvas. Claude's theme controls the outer frame; the README explains why Light theme can leave bright strips in a dark terminal, without changing the user's theme. In a controlled 180-column, 48-row CLI probe, the inline layout fitted the same image into 50 by 14 cells, while a 128-column pane fitted it into 126 by 34 cells. The interactive CLI check verified native paste, cursor entry/exit, hot reload and exit cleanup. The landing-page change has not been visually inspected or deployed.

Test plan

• claude plugin validate plugins/image-peek --strict
• claude plugin validate .claude-plugin/marketplace.json
• claude plugin test plugins/image-peek: 17 passing
• TypeScript diagnostics against the locally generated Claude Code 2.1.287 types
• Existing fable-pin tests: 2 passing; repository Node tests: 6 passing
• Native macOS clipboard helper and actual Claude CLI cursor/reload/cleanup check; no model turn submitted
• User-provided Ghostty screenshot confirms the large image and dark canvas
• In Ghostty, preview two distinct clipboard images, move between their markers, resize the window, and repeat with existing conversation output. Confirm the larger dark pane and keyboard focus. A previously resized pane can override the requested width.
• Repeat the interaction check in iTerm2 3.7.3+ and local Herdr 0.9.1+ inside Ghostty, starting a fresh Claude process with the documented renderer override.
• Visually inspect site/index.html; after the normal site deployment, check its Image Peek card and installation command.