ScreenSight

Let any coding agent see your screen — not just Claude Code.

MCP server + CLI fallback + a standalone watch daemon. No API key required; runs on whatever subscription/session the agent already has.

ScreenSight generalizes screen-awareness beyond a single agent. It ships as:

MCP server — works in Cursor, Windsurf, Cline, Claude Code, Codex CLI, and any MCP-capable agent
CLI — works for Aider, raw shell agents, or any environment that can run a command
Watch daemon — a long-lived background process for interval capture with automatic stop

Inspired by ScreenPipe — this is the agent-agnostic version.

📖 Full documentation: harshitboots.github.io/ScreenSight

Install

From source (recommended)

git clone <repo-url> screensight
cd screensight
# Linux / macOS
bash install.sh
# Windows
.\install.ps1

With pip directly

pip install .

With pipx

pipx install .

Requires Python 3.10+.

MCP Configuration

Add this block to your agent's config file:

{
"mcpServers": {
"screensight": {
"command": "screensight-mcp"
}
}
}

Agent	Config file location
Claude Code	`~/.claude.json` or project `.mcp.json`
Cursor	`~/.cursor/mcp.json`
Windsurf	`~/.codeium/windsurf/mcp_config.json`
Cline	VS Code settings under `cline.mcpServers`
Codex CLI	`~/.codex/config.json`
Aider / no MCP	No config needed — use the CLI directly

MCP Tools (8 total)

Tool	Description
`screen_enable`	Turn ON the master switch
`screen_disable`	Turn OFF the master switch
`screen_status`	Check whether capture is enabled
`screen_capture`	Capture screen, returns image + window title
`screen_watch_start`	Start bounded watch daemon
`screen_watch_stop`	Stop watch daemon
`screen_watch_latest`	Get daemon status and frame count
`screen_list_displays`	List available monitors

CLI Usage

screensight on # Enable capture
screensight off # Disable capture (deletes frame)
screensight status # Check switch state
screensight capture # Capture primary display
screensight capture --display 1 # Capture specific display
screensight watch --interval 5 # Watch every 5s (default)
screensight watch --interval 3 --max-frames 20
screensight watch-stop # Stop watch daemon
screensight watch-status # Check daemon status
screensight displays # List monitors

Example output

// screensight capture
{
"path": "C:\\Users\\you\\.screensight\\frame.jpg",
"sha256": "3d950ca5b88301d1f259bab41a35d6f0ffedd0694ead17c50e28aa4660d6dcf1",
"active_window_title": "main.py - myproject - Visual Studio Code"
}

// screensight watch-status
{
"frames_analyzed": 3,
"last_hash": "15dc34902d50de22a1146a9d8b9dd732f9e5c60d9dfbb41bc5b7f5a72e5bbb8b",
"interval": 5,
"max_frames": 10,
"status": "running",
"running": true
}

Exit codes

Code	Meaning
`0`	Success
`3`	Master switch is off, or capture failed

Privacy

ScreenSight is designed with privacy as a first-class concern. Nothing is captured unless you explicitly enable it.

1. Off by default

The master switch (~/.screensight/state.json) gates every capture. The check happens inside core.capture_once() — not in a prompt or tool description — so no instruction injection can bypass it.

screensight status # Check if it's on
screensight on # Enable capture
screensight off # Disable capture + delete frame

2. Sensitive-app blocklist

Before a frame is saved, the active window title is checked against a blocklist. Matches abort the capture — nothing is saved, nothing is sent.

Default blocklist:

1Password, Bitwarden, KeePass, LastPass
Keychain Access
Private browsing / Incognito windows
Any window with "password" in the title

Customize: Edit ~/.screensight/redact_zones.json:

{
"blocklist": ["1password", "bitwarden", "my-bank-app"],
"zones": []
}

3. Zone redaction

Define fixed screen rectangles that always get blacked out before the frame is saved. Useful for permanent on-screen elements like clock widgets, note apps, or banking tools.

{
"zones": [
{"x": 0, "y": 0, "w": 200, "h": 100, "label": "top-left corner"}
]
}

4. Frame hygiene

One frame file: ~/.screensight/frame.jpg
Overwritten on every capture — never accumulates
Deleted on screensight off
Daemon status: ~/.screensight/daemon.json
Daemon PID: ~/.screensight/daemon.pid

5. Watch mode self-limits

Default max: 10 changed frames per watch session
Auto-stops after --max-frames reached
Turns off the master switch when it exits
Prevents idle daemons from quietly burning tokens

6. Downscale to 1568px

Images are downscaled to 1568px long edge before leaving disk — the point past which more pixels don't help a vision model. Keeps token cost low for all consumers.

Project structure

src/screensight/
__init__.py # Package init
__main__.py # CLI entry point (argparse)
config.py # Paths, constants, blocklist defaults
state.py # Master on/off switch
core.py # capture_once() — single entrypoint
privacy.py # Blocklist check, downscale + zone redaction
diff.py # SHA-256 hashing, change detection
watch.py # Daemon (start/stop/status + loop)
mcp_server.py # FastMCP server (8 tools)
capture/
base.py # CaptureBackend ABC
macos.py # macOS (screencapture + osascript)
linux.py # Linux (grim / gnome-screenshot / import)
windows.py # Windows + WSL (PowerShell + System.Drawing)
tests/
test_state.py # On/off round trip
test_privacy.py # Blocklist matching, zone scaling
test_diff.py # Hash stability, change detection
test_core.py # capture_once() with mocked backend

Comparison

Feature	ScreenSight	ScreenPipe	Agent-specific tools
Works with any MCP agent	✅	❌	❌
CLI fallback (no MCP needed)	✅	❌	Varies
Watch daemon with auto-stop	✅	✅	❌
Master switch (off by default)	✅	❌	Varies
Blocklist + zone redaction	✅	❌	❌
No API key required	✅	✅	Varies
Cross-platform	✅	✅	Varies
1568px downscale for tokens	✅	❌	❌
Frame cleanup on off	✅	❌	❌
Open source	✅	✅	Varies

Development

# Create venv and install in editable mode
python -m venv .venv
source .venv/bin/activate # Linux/macOS
.\.venv\Scripts\Activate.ps1 # Windows
pip install -e .
pip install pytest # For running tests# Run tests
pytest tests/ -v
# Run the MCP server for testing
screensight-mcp # Starts on stdio
fastmcp dev screensight.mcp_server:mcp # Or via fastmcp dev

Platform support

Platform	Status	Backend
Windows	✅ Tested	PowerShell + System.Drawing
macOS	⚠️ Untested	screencapture + osascript
Linux	⚠️ Untested	grim / gnome-screenshot / import + xdotool
WSL	⚠️ Untested	PowerShell (captures Windows desktop)

Contributing

Contributions are welcome — bug fixes, backend improvements, and especially test reports from macOS / Linux / WSL (all currently ⚠️ untested).

Read CONTRIBUTING.md for setup, the test workflow, and the six privacy invariants
PROJECT.md, ARCHITECTURE.md, and AGENTS.md explain the design
Report bugs or platform results via the issue templates
Security issues: see SECURITY.md (report privately, not in public issues)
Need help? See SUPPORT.md

By participating you agree to the Code of Conduct.

License

MIT

Name		Name	Last commit message	Last commit date
.github		.github
docs		docs
examples		examples
skills/claude-code		skills/claude-code
src/screensight		src/screensight
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
GUIDE.md		GUIDE.md
LICENSE		LICENSE
PROJECT.md		PROJECT.md
README.md		README.md
SECURITY.md		SECURITY.md
SUPPORT.md		SUPPORT.md
install.ps1		install.ps1
install.sh		install.sh
llms.txt		llms.txt
mkdocs.yml		mkdocs.yml
pyproject.toml		pyproject.toml
requirements-docs.txt		requirements-docs.txt

Navigation Menu

Repository files navigation

ScreenSight

Install

From source (recommended)

With pip directly

With pipx

MCP Configuration

MCP Tools (8 total)

CLI Usage

Example output

Exit codes

Privacy

1. Off by default

2. Sensitive-app blocklist

3. Zone redaction

4. Frame hygiene

5. Watch mode self-limits

6. Downscale to 1568px

Project structure

Comparison

Development

Platform support

Contributing

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

ScreenSight

Install

From source (recommended)

With pip directly

With pipx

MCP Configuration

MCP Tools (8 total)

CLI Usage

Example output

Exit codes

Privacy

1. Off by default

2. Sensitive-app blocklist

3. Zone redaction

4. Frame hygiene

5. Watch mode self-limits

6. Downscale to 1568px

Project structure

Comparison

Development

Platform support

Contributing

License

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages