Install ScreenPilot

Install ScreenPilot on Windows, macOS or Linux, add it to your AI apps, uninstall it, and fix common problems.

Download the file for your computer, run the installer, then restart your AI app. Everything ScreenPilot needs is inside the download. You do not need to install anything else.

Install your AI app first and open it once. The ScreenPilot installer adds itself to every AI app it finds. If you install a new AI app later, run the ScreenPilot installer again.

Downloads#

Not sure which Mac you have? Open the Apple menu and choose About This Mac. "Chip: Apple M..." means Apple Silicon. "Processor: Intel" means Intel. All versions are on the Releases page.

Windows#

1. Download ScreenPilot-windows-setup.exe and double-click it.
2. If Windows says Windows protected your PC, click More info, then Run anyway. The installer is not signed yet.
3. Click Install. You do not need an administrator password. The first install takes a minute or two, because it also downloads the video renderer (about 100 MB, once).
4. The last page lists the AI apps ScreenPilot was added to. Click Finish.
5. Restart your AI app. Quit it completely, then open it again. For Claude Desktop, right-click its icon next to the clock and choose Quit.

If your antivirus asks about ScreenPilot, allow it. ScreenPilot watches mouse clicks while it records, so it can zoom in on them.

Other ways to install on Windows#

• Claude Desktop only: double-click ScreenPilot-windows.mcpb and click Install in Claude.
• Cannot run installers: download ScreenPilot-windows.zip, right-click it and choose Extract All, then open the folder and double-click ScreenPilot Setup.cmd.

macOS#

1. Download the zip for your Mac and double-click it. You get a ScreenPilot folder.
2. Open the folder and double-click Install ScreenPilot.command.
3. The first time, macOS says it cannot verify the developer. Click Done. Open System Settings, then Privacy & Security, scroll down and click Open Anyway next to "Install ScreenPilot.command", then confirm. Apple has not notarized ScreenPilot yet.
4. A Terminal window shows what was installed. Press Enter to close it. You can delete the downloaded folder now.
5. Restart your AI app (Cmd+Q, then open it again).

macOS permissions#

The first time you ask for a recording, macOS asks you to allow your AI app (Claude, Cursor, Terminal), not ScreenPilot itself. Open System Settings, then Privacy & Security, and turn your AI app on in these lists:

• Screen & System Audio Recording: needed to record.
• Accessibility: needed when the AI uses your apps for you (mouse and keyboard).
• Input Monitoring: optional. It lets recordings zoom in on your own clicks.

Then quit and reopen the AI app. When a permission is missing, ScreenPilot opens the right settings pane and the error names the app to allow.

Claude Desktop only: double-click ScreenPilot-macos-arm64.mcpb (Intel: ScreenPilot-macos-x64.mcpb) and click Install in Claude. The same note about missing Mac builds applies to these files.

Linux#

1. Download ScreenPilot-linux.tar.gz, right-click it and choose Extract Here. You get a ScreenPilot folder.
2. Open the folder and double-click install.sh. Choose Run or Run in Terminal if asked. A terminal window shows what happens. Or open a terminal in the folder and run ./install.sh.
3. Built-in recording on Wayland desktops needs a few system packages (GStreamer). If they are missing, the installer shows the exact command for your distribution (Fedora, Ubuntu, Debian, Mint, Arch or openSUSE) and asks whether to run it. Type y and your password. You can skip this and do it later.
4. Restart your AI app.
5. The first time you record, or let the AI use your desktop, your desktop asks once to allow screen sharing or remote control. Allow it.

What works depends on your desktop. See Platform support for the full table.

Check that it works#

1. Quit your AI app completely and open it again.
2. Ask it: "Run the ScreenPilot doctor." It reports the recorder, permissions, voices and video renderer, and says how to fix what is missing. If you get that report, ScreenPilot is connected.
3. To double-check, look for screenpilot in your AI app's tools or MCP list. In Claude Code, run /mcp (or claude mcp list in a terminal). It should say Connected.
4. Try a real request: "Take a screenshot of my screen." The first time, your desktop may ask to allow screen sharing. Allow it.

Nothing shows up? See If something goes wrong.

What the installer does#

• Copies ScreenPilot to your user folder: %LOCALAPPDATA%\ScreenPilot on Windows, ~/Library/Application Support/ScreenPilot on macOS, and ~/.local/share/screenpilot on Linux.
• Creates the output folder for your videos, inside your Videos folder.
• Adds ScreenPilot to each AI app it finds, and backs up each settings file first. Your other entries and comments stay as they were.
• Downloads and tests the video renderer, the first time only.

AI apps it is added to#

The installer adds ScreenPilot to each of these that it finds:

• Claude Desktop (including the Microsoft Store version) and Claude Code. For Claude Code it also installs the ScreenPilot skill.
• Codex, OpenCode, Gemini CLI, Qwen Code, GitHub Copilot CLI, Amazon Q, Goose, Warp.
• Cursor, Windsurf, Devin Desktop, Antigravity, Kiro, Zed, LM Studio.
• VS Code, VS Code Insiders and VSCodium, plus the Cline and Roo Code extensions.

JetBrains AI Assistant has no settings file. After installing, use its Import from Claude button.

Add it to another app by hand#

Any app that supports MCP servers works. This command prints the settings to copy:

• Windows (Command Prompt): "%LOCALAPPDATA%\ScreenPilot\bin\node.exe" "%LOCALAPPDATA%\ScreenPilot\dist\cli.js" setup --print
• macOS: ~/Library/Application\ Support/ScreenPilot/bin/node ~/Library/Application\ Support/ScreenPilot/dist/cli.js setup --print
• Linux: ~/.local/share/screenpilot/bin/node ~/.local/share/screenpilot/dist/cli.js setup --print

It prints a standard mcpServers entry (command, arguments and environment) that most apps accept. Paste it into the app's MCP settings, then restart the app.

To see which apps setup knows and whether each one is installed, run the same command with setup --list instead of setup --print.

Update and uninstall#

Update: download the new installer and run it. If an AI app is open, the installer asks you to close it first.

• Windows: open Settings, then Apps, then Installed apps, find ScreenPilot and choose Uninstall. It also removes ScreenPilot from your AI apps.
• macOS: double-click Uninstall ScreenPilot.command in the downloaded folder. Download it again if you deleted it.
• Linux: run ./uninstall.sh in the downloaded folder.

Uninstalling removes ScreenPilot from your AI apps. Your videos stay where they are.

If something goes wrong#

• The AI app does not know ScreenPilot. Quit the AI app completely and open it again. Still nothing? Run the installer again. It lists the apps it added ScreenPilot to.
• "No AI tool found". Install your AI app, open it once, then run the ScreenPilot installer again.
• The installer says to close your AI apps. An open AI app is using the old ScreenPilot. Quit it and click Retry.
• "Video renderer: not ready". The one-time download needs internet. Nothing to do: your first video downloads it.
• Recording or mouse control fails on a Mac. Allow your AI app under Screen & System Audio Recording and Accessibility, then quit and reopen it.

Run the doctor#

To check everything at once, ask your AI app: "Run the ScreenPilot doctor." It checks the recorder, permissions, voices and more, and says how to fix what is missing. Developers can run screenpilot doctor in a terminal. More answers are in the FAQ.