[FEATURE] Expose pasted image data to hooks and plugins

[KennyVaneetvelde]

Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• This is a single feature request (not multiple features)

Problem Statement

When users paste images into Claude Code conversations, there is no programmatic way to access the raw image data (base64 or file reference) from hooks, plugins, or skills. Claude can see and analyze images through vision capabilities, but cannot extract or pass the underlying data to external tools.

This makes it impossible to build plugins that save pasted images to disk, process images with external tools like ImageMagick or Pillow, upload images to external services, or include images in automated workflows.

I attempted to build a plugin that saves pasted images to disk. The skill assumes Claude can "extract base64 data" from images, but this is architecturally impossible with current capabilities.

Related issues: #14150 (MCP tool image results), #9567 (Hook environment variables empty), #592 (Allow Claude to see images)

Proposed Solution

Expose image data through one or more of these mechanisms:

Option A: Hook-based access
Add a new hook event UserPromptSubmit that includes image data:

{
  "event": "UserPromptSubmit",
  "prompt": "Save these images",
  "images": [
    {
      "index": 0,
      "media_type": "image/png",
      "base64": "iVBORw0KGgo...",
      "temp_path": "/tmp/claude-images/img_001.png"
    }
  ]
}

Option B: Temporary file references
Automatically save pasted images to a temp directory and provide paths via environment variables:

$CLAUDE_IMAGE_1=/tmp/claude-code/session-abc/image_001.png
$CLAUDE_IMAGE_2=/tmp/claude-code/session-abc/image_002.png

Option C: Built-in tool for image extraction
Provide a built-in tool that plugins/skills can call:

claude-code --get-image 1 --output /path/to/save.png

Alternative Solutions

Current workarounds all have significant limitations:

Asking users to provide file paths instead of pasting defeats the purpose of the paste feature and degrades UX. Using clipboard-reading Python scripts only works if user just copied the image, and doesn't work for multiple images or images pasted earlier in conversation. Having users manually save images first adds friction and requires user to remember filenames.

Use cases this would enable: saving screenshots to organized folders with meaningful names, processing/compressing images before analysis, integrating with asset pipelines like Obsidian vaults, and extracting text via external OCR tools.

Priority

High - Significant impact on productivity

Feature Category

Developer tools/SDK

Use Case Example

I'm building a plugin to organize YouTube video notes in Obsidian. User pastes 6 screenshots from a tutorial video into the conversation. User says "save these images to my Obsidian vault with timestamps". With this feature, my plugin could access the raw image data via hook or environment variable, save each image to the appropriate Assets folder, and name them based on context (e.g., "Rule_of_Octave_timestamp_1.png"). Currently this is impossible because Claude can see the images but cannot extract their data to save them.

Additional Context

Environment: Windows 11, Claude Code 2.x

The Claude API supports images via base64, URL, or Files API - but Claude Code doesn't expose this data to plugins/hooks after images are pasted into a conversation.