Image in Comment allows you to paste images directly into your code comments and view them on hover. Perfect for documenting UI components, architectural diagrams, or visual bugs directly where the code lives.
Features
- Paste Images: Use
Cmd+Shift+V (Mac) or Ctrl+Shift+V (Windows/Linux) to paste an image from your clipboard into a comment.
- Automatic Compression: Images are automatically resized based on source dimensions and converted to optimized
.webp format.
- Configurable Storage: Images are saved in a configurable directory (default:
.images/ in your workspace root).
- Hover Preview: Hover over any
@image tag in a comment to see an inline thumbnail preview.
- Full-Size Preview: Click "Open Full Preview" in the hover tooltip to view images in a dedicated panel at full size.
- Multi-Language Support: Supports comment styles for JS/TS, Python, HTML/XML, CSS, Shell, Lua, SQL, and many more.
Usage
- Take a screenshot or copy an image to your clipboard.
- Place your cursor in a code file where you want the comment.
- Press
Cmd+Shift+V (Mac) or Ctrl+Shift+V (Windows/Linux).
- The extension will generate a comment with an
@image tag pointing to the saved file.
- Hover over the
@image <path> text to see an inline preview.
- Click "Open Preview" in the hover tooltip to view the image at full size in a dedicated panel.
Requirements
This extension relies on system tools to read from the clipboard:
Extension Settings
This extension contributes the following settings:
imageInComment.imageDirectory: Configure the directory where images are stored (relative to workspace root).
- Default:
.images
- Example: Set to
assets/screenshots to store images in that directory instead.
imageInComment.autoCleanupOnSave: Automatically delete orphaned images that are no longer referenced by any @image tag in your workspace.
- Default:
true
- Note: If you disable this, you will need to manually run the
Image in Comment: Clean up unused images command to prevent your image directory from filling up with deleted comment images.
imageInComment.unusedImageRetentionDays: Number of days to keep an orphaned image before deleting it.
- Default:
5
- Note: This acts as a grace period in case you accidentally cut an image comment, save the file, and plan to paste it back later. If you want images gone immediately, update this setting to
0 or delete them manually.
To change this setting:
- Open VS Code Settings (
Cmd+, on Mac or Ctrl+, on Windows/Linux)
- Search for "Image in Comment"
- Update the "Image Directory", "Auto Cleanup On Save", or "Retention Days" fields
Or add to your settings.json:
{
"imageInComment.imageDirectory": "assets/screenshots",
"imageInComment.autoCleanupOnSave": true,
"imageInComment.unusedImageRetentionDays": 5
}
[!WARNING]
Garbage Collection: By default, this extension will automatically search for and delete any images in your .images directory that do not have a corresponding @image comment tag in your workspace after 5 days. If you rename, copy/cut, or temporally delete a comment and save, you have 5 days to paste it back before the image is permanently deleted from the filesystem. If you want a longer grace period, increase the unusedImageRetentionDays setting.
Image Compression
Images are automatically optimized when pasted using adaptive compression tiers based on the source image size:
| Source Width |
Max Output Width |
Quality |
Best For |
| ≤ 1280px |
No resize |
85% |
Small screenshots, icons |
| ≤ 2560px |
1600px |
80% |
Standard HD / 1440p monitors |
| ≤ 3840px |
2400px |
75% |
Ultrawide / 4K monitors |
| > 3840px |
3200px |
70% |
5K+ / multi-monitor setups |
- WebP Conversion: All images are converted to the modern WebP format for better compression.
- Aspect Ratio Preserved: Images are only resized by width; height scales proportionally.
- No Upscaling: Images smaller than the tier's max width are never enlarged.
- Typical Savings: Most screenshots compress to 50–200 KB (compared to 500 KB+ for unoptimized PNGs).
These optimizations happen automatically without any configuration needed.
Known Issues
- Images are stored locally in your configured image directory (default:
.images/). You must commit this folder to your version control system for others to see the images.
- macOS Intel (x64) is not supported. Pre-built binaries are only shipped for Apple Silicon (arm64), Linux x64, and Windows x64.
Enjoy documenting visually!
Links
