Screen Review

ScrnReview – Instant screenshot review for Gemini CLI. One command. Zero clutter.

• Gemini CLI plugin tool
• Copyright (c) 2025 Josh McCann

A minimalist Python tool that captures a screenshot, sends it to Gemini CLI for visual review, and deletes the image afterward. No global installs. No setup headaches.

---

Installation

Clone the repo and install locally:

git clone https://github.com/ArtisticMusician/ScreenReview.git
cd ScreenReview
pip install .

This installs the CLI command scrnreview.

---

Usage

scrnreview

Optional Flags

• --keep : Keep the screenshot after review
• --reset-env : Rebuild the virtual environment from scratch
• --output-dir <path> : Save screenshot to a specific folder (used with --keep)

Example

scrnreview --keep --output-dir screenshots

This saves a file like scrnreview_20250813_235959.png in the screenshots/ folder.

---

Gemini CLI Integration

To use ScrnReview as part of a Gemini CLI workflow:

1. Ensure scrnreview is installed and in your system PATH
   Run pip install . from the project root.

2. Register ScrnReview in your Gemini CLI settings.json
   Add this to your user or project-level config:

   {
     "tools": {
       "scrnreview": {
         "command": "scrnreview",
         "args": ["--keep", "--output-dir", "screenshots"],
         "description": "Capture and review screenshot using ScrnReview"
       }
     }
   }

3. Prompt Gemini to use it

   “Capture a screenshot and review it using ScrnReview. Retain the image in screenshots/.”

ScrnReview is designed to be deterministic and ephemeral—perfect for plan-keeper flows and visual UI review.

---

Troubleshooting

Verify Your Setup

Run this script to check your environment:

It checks:

• Python version
• pyautogui installation
• Gemini CLI availability
• scrnreview CLI install
• macOS screen recording permission (hint only)
• If anything’s missing, it’ll tell you how to fix it.

Want me to prep a matching Makefile or tasks.py for automation next? Or scaffold a docs/ folder with usage examples and screenshots?



python verify-install.py

### Python Version

ScrnReview requires Python 3.7 or newer.

Check your version:

```bash
python --version

If it’s older than 3.7, install the latest version from python.org.

---

CLI Not Found After Install

If scrnreview isn’t recognized after install, your Python Scripts/ or bin/ folder may not be in your system PATH.

Windows

Add this to your PATH:

C:\Users\<yourname>\AppData\Local\Programs\Python\PythonXX\Scripts\

Replace PythonXX with your actual Python version (e.g. Python311).
Then restart your terminal or log out and back in.

macOS/Linux

Add this to your shell config (~/.bashrc, ~/.zshrc, etc.):

export PATH="$HOME/.local/bin:$PATH"

Then reload your shell:

source ~/.bashrc   # or ~/.zshrc

---

Gemini CLI Not Installed

ScrnReview calls gemini --review-ui <image>. Make sure Gemini CLI is installed and available in your PATH.

Test it:

gemini --version

If this fails, install Gemini CLI and ensure it’s accessible from your terminal.

---

Screenshot Permissions (macOS)

If screenshots fail or are blank, go to:

System Settings → Privacy & Security → Screen Recording

Then allow your terminal app (e.g. Terminal, iTerm2) to record the screen.

---

Platform Notes

Linux

You may need to install additional packages:

sudo apt install python3-tk python3-xlib

macOS

No extra packages needed, but screen recording permissions may be required.

Windows

No extra packages needed. If you see a blank screenshot, check your display permissions.

---

Virtual Environment Issues

If ScrnReview fails to launch or throws import errors, try:

scrnreview --reset-env

This rebuilds the internal virtual environment from scratch.

---

Output Directory Behavior

ScrnReview will auto-create the folder you specify with --output-dir.
If the directory isn’t writable (e.g. system folders), the tool will fail. Use a local folder like screenshots/.

---

Screenshot Location

If you use --keep, screenshots are saved in the folder specified by --output-dir.
If you don’t specify one, they’re saved in the current working directory.

Files are named like:

scrnreview_YYYYMMDD_HHMMSS.png

---

Manual Execution Warning

You can run ScrnReview.py directly, but it will auto-create a virtual environment and install dependencies.
For best results, install via pip install . and use the scrnreview CLI.

---

Launcher Scripts

• launch_scrnreview.bat – Windows double-click launcher
• launch_scrnreview.sh – macOS/Linux launcher (chmod +x required)

---

Requirements

• Python 3.7+
• Gemini CLI installed and available in PATH

---

Author

Created and maintained by Josh McCann

---

License

MIT License – see LICENSE