cli-eyes

Screenshot capture for AI context -- hotkey to clipboard to Claude.

Quick Start

npm install -g cli-eyes
cli-eyes setup
cli-eyes capture

That's it. The screenshot path is automatically injected into your active terminal, ready for Claude Code or any AI assistant to read.

What It Does

cli-eyes captures screenshots via CLI or global hotkey and auto-injects the file path into your active terminal session. Built for developers using AI assistants like Claude Code that can read local files.

Hotkey / CLI  -->  macOS screencapture  -->  ~/.cli-eyes/screenshot.png
                                                    |
                                             path injected into terminal
                                                    |
                                             Claude reads the image

Installation

npm (recommended)

npm install -g cli-eyes

Requirements:

• macOS (not available on Linux or Windows)
• Node.js 20 or later
• Xcode Command Line Tools (for hotkey daemon compilation): xcode-select --install

The eyes alias is also installed -- you can use eyes capture instead of cli-eyes capture.

Homebrew

brew tap <owner>/cli-eyes && brew install cli-eyes

Note: Replace <owner> with the GitHub username/org when the tap is published.

First Run

Run the interactive setup to configure permissions and shell integration:

cli-eyes setup

This will:

1. Check Screen Recording permission (required for all captures)
2. Check Accessibility permission (required for terminal injection and hotkeys)
3. Install a shell session cleanup hook (removes screenshots when terminal closes)

Each permission opens System Settings to the correct pane if not already granted.

Usage

Capture Commands

# Region select (default)
cli-eyes capture
cli-eyes capture -r

# Fullscreen
cli-eyes capture -f

# Active window
cli-eyes capture -w

# Custom filename
cli-eyes capture --name "error-state"

# Specific monitor
cli-eyes capture --display 2

# Also copy image to clipboard
cli-eyes capture --clipboard

# Stdout only, no terminal injection
cli-eyes capture --no-inject

Configuration

# View current configuration
cli-eyes config

# Change a setting
cli-eyes config set bufferSize 10

Hotkey Daemon

# Start/stop the hotkey daemon
cli-eyes daemon start
cli-eyes daemon stop
cli-eyes daemon status

# Auto-start on login
cli-eyes daemon install
cli-eyes daemon uninstall

Other Commands

# Remove session screenshots
cli-eyes cleanup

# Show recent captures from manifest
cli-eyes status

Hotkeys

Default bindings (when daemon is running):

| Shortcut | Action | |---|---| | Ctrl+Shift+1 | Region select capture | | Ctrl+Shift+2 | Fullscreen capture | | Ctrl+Shift+3 | Window capture |

Customize hotkeys via configuration:

cli-eyes config set hotkeys.region "ctrl+shift+1"

Terminal Support

cli-eyes detects your active terminal and uses the best injection method:

| Terminal | Injection Method | |---|---| | Terminal.app | AppleScript keystroke | | iTerm2 | AppleScript write text | | Kitty | Remote control protocol | | Others | Clipboard + Cmd+V fallback |

The terminal is detected before capture starts (since screencapture steals focus). If injection fails, the path is still printed to stdout.

Configuration

Configuration is stored at ~/.cli-eyes/config.json.

| Setting | Default | Description | |---|---|---| | screenshotDir | ~/.cli-eyes | Where screenshots are saved | | bufferSize | 5 | Max screenshots to keep (rolling buffer) | | hotkeys.region | ctrl+shift+1 | Region capture hotkey | | hotkeys.fullscreen | ctrl+shift+2 | Fullscreen capture hotkey | | hotkeys.window | ctrl+shift+3 | Window capture hotkey | | daemonBinaryPath | auto-detected | Path to the compiled Swift daemon |

Permissions

cli-eyes requires macOS permissions to function. The setup command guides you through granting them.

Screen Recording

Required for all captures. Without this, screencapture produces blank images.

Grant via: System Settings > Privacy & Security > Screen Recording > enable your terminal app.

Accessibility

Required for terminal injection and hotkeys. Allows cli-eyes to type the screenshot path into your terminal.

Grant via: System Settings > Privacy & Security > Accessibility > enable your terminal app.

Input Monitoring

Required for the hotkey daemon. Allows the daemon to listen for global keyboard shortcuts.

Grant via: System Settings > Privacy & Security > Input Monitoring > enable cli-eyes-daemon.

How It Works

cli-eyes is a Node.js CLI that wraps the macOS screencapture binary. Key components:

• Capture engine: Spawns screencapture with appropriate flags for region/fullscreen/window modes
• Rolling buffer: Manages up to N screenshots in ~/.cli-eyes/, auto-deleting oldest files
• Manifest: Tracks all captures with timestamps in ~/.cli-eyes/manifest.json
• Terminal injection: Detects the active terminal app and uses AppleScript or clipboard to inject the file path
• Hotkey daemon: A Swift binary using CGEventTap for global keyboard shortcuts, communicating with the CLI via the capture command
• Session cleanup: Shell trap hook that removes session screenshots when the terminal closes

License

MIT