screenshot-anything-macos
Give Gemini CLI the ability to see your screen. Capture full screen or specific windows on-demand for visual debugging, UI analysis, and con
Open source Open in the app JSON README (API)
About
Give Gemini CLI the ability to see your screen. Capture full screen or specific windows on-demand for visual debugging, UI analysis, and context gathering.
Details
- Kind
- Plugins
- Topic
- Developer tools
- Publisher
- lyalindotcom
- Origin
- gemini
- Category
- ferramentas
- Version
- 1.0.3
- Stars
- 24
- Forks
- 4
- Last push
- 2025-12-20T19:33:31Z
- Repository state
- ativo
- Language
- TypeScript
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
lyalindotcom/screenshotextension
README
# Screenshot Anything (macOS only)
A Gemini CLI extension that gives the AI the ability to see your screen. Capture full screen or specific application windows on-demand for visual debugging, UI analysis, and context gathering.
## Features
- **On-Demand Capture**: Screenshots are only taken when you ask (e.g., "Look at my screen")
- **Window Locking**: Focus captures on a specific application window using fuzzy search
- **Smart Countdown**: 3-second visual countdown for full-screen captures; instant capture for locked windows
- **Optimized Images**: Automatically resized and compressed for fast response times
- **Session History**: View previously captured screenshots from the current session
- **Multi-Display Support**: Capture from any connected display
- **Local Privacy**: Images are processed locally and saved to a session folder for your reference
## Requirements
- **macOS** (this extension uses macOS-specific APIs)
- **Node.js** v18 or later
- **Xcode Command Line Tools** (for window enumeration)
```bash
xcode-select --install
```
- **Screen Recording Permission** (you'll be prompted on first use)
## Installation
### From GitHub
```bash
gemini extensions install https://github.com/LyalinDotCom/ScreenshotExtension
```
The extension will automatically build during installation.
### Local Development
1. Clone the repository:
```bash
git clone https://github.com/LyalinDotCom/ScreenshotExtension.git
cd ScreenshotExtension
```
2. Install dependencies:
```bash
npm install
```
3. Link to Gemini CLI:
```bash
gemini extensions link .
```
## Usage
Once installed, Gemini will automatically use the screenshot tool when you ask it to look at your screen.
### Natural Language Examples
- "Look at my screen and tell me what error is in the console."
- "Take a screenshot and analyze the layout of this web page."
- "I'm stuck on this screen, what should I click?"
- "What version number is shown in the bottom corner?"
### Custom Commands
| Command | Description |
|---------|-------------|
| `/shot` | Take a screenshot of the full screen or locked window |
| `/list` | List all open visible windows |
| `/lock <query>` | Lock captures to a window matching the query (e.g., `/lock Chrome`) |
| `/clear` | Clear the window lock, revert to full screen capture |
### Window Locking Workflow
1. Use `/list` to see all available windows
2. Use `/lock VS Code` to focus on a specific window
3. Use `/shot` or ask naturally - captures will only show that window
4. Use `/clear` to go back to full screen capture
## MCP Tools
This extension provides the following tools to the AI:
| Tool | Description |
|------|-------------|
| `take_screenshot` | Captures the screen or locked window, returns the image |
| `view_screenshot_history` | Lists or retrieves previously captured screenshots |
| `list_windows` | Lists all visible application windows |
| `focus_window` | Locks capture to a specific window by fuzzy search |
| `clear_lock` | Removes the window lock |
## Limitations
- **macOS only**: Uses CoreGraphics APIs and `screencapture` utility
- **Screen Recording permission required**: Must be granted in System Settings
- **Xcode CLI tools required**: Needed for Swift-based window enumeration
- **3-second countdown**: For full-screen captures only (locked windows capture instantly)
## Troubleshooting
### Permission Denied
On first run, macOS will prompt you to allow screen recording. If you denied it:
1. Go to **System Settings > Privacy & Security > Screen Recording**
2. Enable the toggle for your Terminal app (Terminal, iTerm, VS Code, etc.)
3. Restart your terminal and the Gemini CLI
### Window List Empty or Missing Apps
Ensure Xcode Command Line Tools are installed:
```bash
xcode-select --install
```
### Multiple Displays
The extension defaults to the primary display (index 0). To capture another display, mention it in your prompt (e.g., "take a screenshot of my second monitor").
## File Storage
Screenshots are saved locally to:
```
./captures/session-{uuid}/
```
Each session gets a unique folder. Images are saved as compressed JPEGs (1280px width, 80% quality).
## License
MIT