claude-image-view README

The project's README from github.com/jarrodwatts/claude-image-view. As one markdown file: README.md.

Claude Image View

A Claude Code mod that shows the images you paste, so you see thumbnails above your prompt instead of bare [Image #1] tags.

License Stars

Claude Image View in action

Install

Inside Claude Code, run:

/plugin marketplace add jarrodwatts/claude-image-view
/plugin install image-view
/reload-plugins

That's it. Paste an image into the prompt and its thumbnail appears above the input.

Prefer the terminal? 
claude plugin marketplace add jarrodwatts/claude-image-view
claude plugin install image-view@claude-image-view

Then run /reload-plugins inside a session, or start a new one.

What You See

Paste one or more images and a row of thumbnails sits above the prompt, each labelled with the number of its tag:

╭────────────────────────╮ ╭────────────╮
│                        │ │            │
│      (screenshot)      │ │  (photo)   │
│                        │ │            │
│           #1           │ │     #2     │
╰────────────────────────╯ ╰────────────╯
❯ why is the header misaligned here [Image #1] vs [Image #2]

How It Works

Claude Code saves every pasted image to a cache folder for the session, as <tmp>/<project>/<session>/images/<n>.png, and puts an [Image #n] tag in the prompt. Claude Image View is a mod:

  1. Every 200ms it reads the prompt box and looks for [Image #n] tags. It checks on a timer because pasting an image doesn't raise an edit event.
  2. For each tag it finds the cached PNG and reads its size from the PNG header.
  3. It draws the thumbnails in the band above the prompt with Claude Code's Image element. The terminal reads the file itself, so the image data never passes through the mod.

Security

Claude Image View is local-only. It makes no network requests and writes no files. It reads the prompt box, lists Claude Code's temp folder to find the current session's image cache, and reads the first bytes of each pasted image. If CLAUDE_CODE_TMPDIR isn't set, it runs id -u once to find the default temp folder.

Run claude plugin validate on the repo to see every event it hooks and every call it makes.

Requirements

Other terminals show [Image #n] in each tile instead of the picture. The Claude Desktop app already previews pasted images, so the mod draws nothing there.

Troubleshooting

Nothing appears when I paste. Run /plugin and check the dim line under the tabs lists image-view as an active mod. If it isn't listed, run /reload-plugins.

The tile says "no preview". The mod couldn't find the cached file. Claude Code may have moved where it stores pasted images. Please open an issue with your Claude Code version.

The tile shows [Image #1] text instead of the picture. Your terminal doesn't support the kitty graphics protocol. See Requirements.

The tile shows [Image #1] text in agent view or a background session, even in Ghostty or kitty. Claude Code turns terminal images off for background sessions. If you attach from a terminal with the kitty graphics protocol, turn them back on in the env block of ~/.claude/settings.json, then start a new session:

"env": { "CLAUDE_CODE_FORCE_TERMINAL_IMAGES": "1" }

Development

git clone https://github.com/jarrodwatts/claude-image-view
cd claude-image-view

# Load it for one session without installing
claude --plugin-dir .

# Check it and run the tests
claude plugin validate .
claude plugin test .

Claude Code writes the API types into .claude-plugin/types/ the first time it loads the mod, and tsc -p . type-checks it from then on.

License

MIT. See LICENSE.

Star History

Star History Chart

claude-image-view (jarrodwatts/claude-image-view)

Searching Database…

240 ·GitHub
Claude-image-view
What is this?Claude Image View is a Claude Code mod that shows thumbnails of images you paste into the prompt, instead of bare [Image #1] text tags.
Is this a standalone app or a plugin for Claude Code?It's a plugin (mod) that loads inside an existing Claude Code terminal session rather than a separate application; Claude Code even generates its API types for the mod on first load.
How do I get it running?Install it from inside Claude Code, then just paste an image into the prompt and its thumbnail appears above the input automatically; if nothing shows, run /reload-plugins or start a new session.
What do I need for this to actually work?You need Claude Code v2.1.287 or later with mods support, running on macOS or Linux, inside a terminal that supports the kitty graphics protocol, such as Ghostty or kitty.
Does the thumbnail preview always work?No: terminals without the kitty graphics protocol just show the raw [Image #n] text instead of a picture, and Claude Code also disables terminal images for background or agent-view sessions unless you re-enable them in settings.json.
Does this mod send my pasted images anywhere?No, it's local-only: it makes no network requests and writes no files, only reading the prompt box and the PNGs Claude Code already cached locally for the session.
Does it do anything inside the Claude Desktop app?No, Claude Desktop already previews pasted images on its own, so the mod draws nothing there.
How does it actually find and render the images?Every 200ms it scans the prompt box for [Image #n] tags, matches each one to the PNG Claude Code cached for that session, reads the size from the PNG header, and draws it above the prompt using Claude Code's Image element.
What does a 'no preview' tile mean?It means the mod couldn't locate the cached PNG for that tag, usually because Claude Code changed where it stores pasted images; the fix suggested is to open an issue with your Claude Code version.
What are similar projects?gyotaku, claude-db, flyingmouse-format, revpdf-release, jevmem, lazy-frames, agent-router, vibe-aso
Which topics is it in?ghostty, terminal-emulators, screenshot, claude-code-plugin, image, cli-tool, image-processing, offline, utility, local-first, plugin, claude
Creator
jarrodwatts
Size
0.4 MB
Stars
240
Updated
CommitOct 12Releasev0.2.0Oct 12
Age
16d
Commits · 90 Days