Browse and preview images pasted into Claude Code sessions — directly from your Mac.

Claude Code displays pasted images as [Image #N] placeholders. cc-preview extracts those images and lets you browse, preview, and copy them with a keyboard-driven native UI powered by Hammerspoon.

Quick Start

brew install Watari995/tap/cc-preview
cc-preview install

Then press Cmd+Shift+R in Hammerspoon to reload, and open cc-preview with Cmd+Shift+I.

Installation

Homebrew (recommended)

brew install Watari995/tap/cc-preview

Binary download

Download the latest binary for your Mac from Releases, then place it in your PATH:

# Apple Silicon
curl -L https://github.com/Watari995/cc-preview/releases/latest/download/cc-preview_darwin_arm64.tar.gz | tar xz
sudo mv cc-preview /usr/local/bin/

# Intel
curl -L https://github.com/Watari995/cc-preview/releases/latest/download/cc-preview_darwin_amd64.tar.gz | tar xz
sudo mv cc-preview /usr/local/bin/

Go install

go install github.com/Watari995/cc-preview@latest

Setup

After installing the binary, run the one-time installer:

This automatically:

• Registers a SessionStart hook in ~/.claude/settings.json
• Deploys the Hammerspoon script to ~/.hammerspoon/
• Updates ~/.hammerspoon/init.lua

Then reload Hammerspoon (Cmd+Shift+R).

Requirements

• macOS
• Claude Code
• Hammerspoon

Usage

How it works

1. A SessionStart hook records each Claude Code session to ~/.claude-preview/sessions.json
2. cc-preview sessions lists sessions that contain images
3. cc-preview images <session-id> extracts base64-encoded images from the JSONL transcript and caches them under ~/.claude-preview/image-cache/
4. The Hammerspoon script calls these commands and renders a native macOS chooser UI

Configuration

Edit the config table at the top of ~/.hammerspoon/cc-preview.lua:

local config = {
    copyMods = {"cmd"},  -- modifiers for copy shortcut
    copyKey  = "c",      -- key for copy shortcut
}

To change the global shortcut (default Cmd+Shift+I):

hs.hotkey.bind({"cmd", "shift"}, "I", showSessions)

License

MIT — see LICENSE