A powerful and simple macOS screenshot plugin for Neovim.
- 🖼️ Two Core Screenshot Modes - Window selection and area selection screenshots
- 📋 Smart Clipboard - Automatically copies screenshot path to system clipboard
- 📁 File Management - Smart naming, directory organization, duplicate detection
- 📊 Professional Logging - Integrated logging system with structured logs
- ⚙️ Highly Configurable - Rich customization options and keybindings
- 🔍 Health Check - Complete system status monitoring and permission detection
- 🧪 Complete Testing - Unit test and integration test coverage
- 📖 Detailed Documentation - Vim help documentation and usage guides
- Operating System: macOS 10.15 (Catalina) or higher
- Neovim: 0.7+ (recommended 0.10+)
- Commands:
screencapture(macOS built-in) - Permissions: Screen Recording permission (required)
Using lazy.nvim
{
"pittcat/macos-screenshot.nvim",
config = function()
require("macos-screenshot").setup({
save_path = "~/Documents/Screenshots",
filename_format = "%Y%m%d_%H%M%S",
copy_path_format = "home", -- Use ~ path
-- Debug mode configuration (optional)
debug = {
auto_enable = false, -- Set to true to auto-enable debug
log_levels = {"info", "warn", "error"},
save_system_info = true
},
keybindings = {
enabled = true,
full_screen = "<leader>ss", -- Window selection screenshot
selection = "<leader>sp" -- Selection screenshot
}
})
end,
-- Lazy loading
cmd = {
"Screenshot",
"ScreenshotSelect"
},
keys = {
{ "<leader>ss", "<cmd>Screenshot<cr>", desc = "Window selection screenshot" },
{ "<leader>sp", "<cmd>ScreenshotSelect<cr>", desc = "Selection screenshot" },
},
-- Only load on macOS
cond = function()
return vim.fn.has("mac") == 1
end,
}require("macos-screenshot").setup({
-- Basic settings
save_path = "~/Desktop/Screenshots", -- Screenshot save path
filename_format = "%Y%m%d_%H%M%S", -- Filename format (strftime)
include_cursor = false, -- Whether to include mouse cursor
play_sound = false, -- Whether to play screenshot sound
copy_path_format = "absolute", -- Clipboard path format: "absolute", "relative", "home"
monitor_screenshots = true, -- Whether to monitor screenshot directory
-- Log configuration
log = {
level = "info", -- Log level: trace, debug, info, warn, error, fatal
use_console = true, -- Console output
use_file = true, -- File output
highlights = true, -- Syntax highlighting
float_precision = 0.01 -- Float precision
},
-- Debug mode configuration
debug = {
auto_enable = false, -- Whether to auto-enable debug mode
log_levels = {"trace", "debug", "info", "warn"}, -- Log levels for debug mode
save_system_info = true -- Whether to save system information
},
-- Keybinding configuration
keybindings = {
enabled = true, -- Whether to enable keybindings
full_screen = "<leader>ss", -- Window selection screenshot
selection = "<leader>sp" -- Selection screenshot
}
})" Core screenshot commands
:Screenshot " Window selection screenshot (click to select a window)
:ScreenshotSelect " Selection screenshot (drag to select area)<leader>ss- Window selection screenshot (click to select a window)<leader>sp- Selection screenshot (drag to select area)
local screenshot = require("macos-screenshot")
-- Screenshots
screenshot.take_screenshot("full") -- Window selection screenshot
screenshot.take_screenshot("selection") -- Selection screenshot
-- Status check
screenshot.is_initialized() -- Check if initialized
screenshot.get_config() -- Get current configuration
screenshot.get_state() -- Get plugin state (for debugging)Run health check to ensure the plugin works properly:
:checkhealth macos-screenshotHealth check verifies:
- macOS environment
- Neovim version compatibility
screencapturecommand availability- Screen recording permissions
- Save directory permissions
- Clipboard functionality
- Logging system
The plugin supports detailed debug mode for troubleshooting and development debugging. Debug mode saves detailed logs to a fixed location for easy tracking and analysis.
" Enable debug mode
:ScreenshotDebugEnable
" Disable debug mode
:ScreenshotDebugDisablerequire("macos-screenshot").setup({
debug = {
auto_enable = true, -- Auto-enable debug mode
log_levels = {"trace", "debug", "info", "warn"}, -- Supported log levels
save_system_info = true -- Save system info when enabled
}
})-- Developers can use more detailed configuration
require("macos-screenshot").setup({
log = {
level = "debug", -- Set log level to debug
use_console = true,
use_file = true
},
debug = {
auto_enable = true,
log_levels = {"trace", "debug", "info", "warn", "error"},
save_system_info = true
}
})Fixed Log File:
- 📁 File Location:
/tmp/macos-screenshot-debug.log - 🔄 Update Strategy: Each debug mode activation replaces the previous log
- 🔒 Fixed Filename: Easy to find and monitor, can use
tail -ffor monitoring - 📈 System Information: Automatically records system environment and plugin state
Log Level Support:
trace- Most detailed trace informationdebug- Debug information and variable statesinfo- General information and operation resultswarn- Warning informationerror- Error information and exceptions
System Information:
- 💻 macOS version and architecture information
- 🎯 Neovim version and API compatibility
- 📂 Working directory and plugin paths
- 🔧 Environment variables and configuration information
Operation Records:
- ⏱️ Detailed operation timeline and execution time
- 📷 Screenshot command construction and execution process
- 📄 File creation, size and path information
- 📎 Clipboard operations and path formatting
Error Diagnosis:
- 🚫 Detailed error stack traces
- 🔐 Permission checks and system requirement verification
⚠️ Warning and exception handling
Debug Commands:
:ScreenshotDebugEnable " Enable debug mode
:ScreenshotDebugDisable " Disable debug mode
:ScreenshotDebugLog " Open debug log file
:ScreenshotDebugTail [N] " Show last N lines of debug log
:ScreenshotDebugClear " Clear debug log
:ScreenshotDebugInfo " Show debug information" 1. Enable debug mode
:ScreenshotDebugEnable
" 2. Test screenshot functionality
:Screenshot
" 3. Check debug logs
:ScreenshotDebugTail 10 " View last 10 lines of log
:ScreenshotDebugLog " Open complete log file
" 4. Disable debug mode
:ScreenshotDebugDisable# Real-time log monitoring in terminal
tail -f /tmp/macos-screenshot-debug.log
# Find specific errors
grep -i error /tmp/macos-screenshot-debug.log
# View screenshot operations
grep "screenshot_" /tmp/macos-screenshot-debug.log" 1. Check health status
:checkhealth macos-screenshot
" 2. Enable debug and get detailed info
:ScreenshotDebugEnable
:ScreenshotDebugInfo
" 3. Clear old logs and retest
:ScreenshotDebugClear
:Screenshot
" 4. View error logs
:ScreenshotDebugTail 20Q: Debug mode not effective?
" Check debug status
:ScreenshotDebugInfo
" Ensure properly enabled
:ScreenshotDebugEnableQ: Can't find log file?
# Find log file location
ls -la /tmp/macos-screenshot-debug.log
# Check directory permissions
ls -ld /tmpQ: Too much detailed logs?
-- Adjust log levels
require("macos-screenshot").setup({
debug = {
log_levels = {"info", "warn", "error"} -- Only show important info
}
})Q: Performance impact?
- Debug mode has slight performance impact, enable only when needed
- Disable promptly after use:
:ScreenshotDebugDisable
MIT License - see LICENSE file for details.
This plugin pairs perfectly with claudecode.nvim to bridge the gap where Claude Code CLI doesn't support direct image pasting like Cursor.
With this integration:
- Take screenshots directly in Neovim using
macos-screenshot.nvim - Screenshots are automatically saved and paths copied to clipboard
- Paste the screenshot paths in Claude Code conversations
- Maintain seamless AI-assisted development workflow
Perfect complement for developers using Claude Code who need visual context sharing capabilities.
Contributions are welcome! Please feel free to submit a Pull Request.
If you encounter any issues or have feature requests, please:
- Check the health check results
- Enable debug mode to collect logs
- Open an issue with detailed information
Note: This plugin only works on macOS and requires Screen Recording permission to function properly.