Install
Windows 10 (version 1903 or later) and 11: run the installer. It installs for your user only, so no admin rights are needed, and adds the sidehand command to your PATH. You can also unzip the portable build anywhere.
macOS 13 Ventura or later: open the DMG and drag Sidehand to Applications. Then make the command available in Terminal:
sudo ln -sf /Applications/Sidehand.app/Contents/MacOS/sidehand /usr/local/bin/sidehand
Connect your AI app
sidehand connect claude-desktop sidehand connect claude-code sidehand connect cursor sidehand connect vscode sidehand connect windsurf
Sidehand adds itself to that app's MCP settings and keeps a dated backup of the old file. Restart the app afterwards. sidehand disconnect <app> removes it again. For any other MCP client, start sidehand serve as a stdio server.
macOS permissions
The first time an agent acts, macOS asks you to allow the app that runs Sidehand (Claude, Cursor, VS Code or Terminal) in System Settings, Privacy & Security:
- Accessibility is required. It lets agents read and press controls.
- Screen Recording is only needed for screenshots. Agents can work without it.
Restart that app after allowing it. sidehand doctor shows anything still missing.
First run
Ask your assistant: "Open Notepad (TextEdit on a Mac) and write a short poem about mice." A blue cursor with the agent's name tag appears and does the work. Keep typing in your own window while it does.
Pausing agents
Press Ctrl Alt F12 on Windows or ⌃ ⌥ ⌘ P on a Mac. Every agent stops before its next action and the cursors turn grey. Press it again to resume. The tray or menu-bar icon and sidehand pause / sidehand resume do the same.
License
After installing, Sidehand opens your browser once: sign in with the account you bought it with and click Connect this computer. Until the computer is connected, agents can look at windows but not click or type.
sidehand status
Your plan decides how many agents work at once (Solo 1, Crew 3, Fleet 5 on each computer) and on how many computers (Solo and Crew 1, Fleet 3). To move to another computer, choose Release this computer in Sidehand's settings or on My licenses, then connect the new one. Sidehand checks the license with our server when you connect and during the daily update check, and keeps working offline for up to 30 days between checks.
Tools
Every acting tool reports via, the path it used (uia for the accessibility API, background for events sent only to the app, real for the borrowed pointer or keyboard), and committed: yes, maybe (look before repeating) or no (nothing was sent).
| Tool | What it does |
|---|---|
launch_app | Starts an app and creates an agent locked to its new window, then hands focus back to you. |
create_agent, lock_agent | An agent with its own cursor, optionally locked to an existing window (starts read-only). |
allow_edits | Lifts read-only protection after you said yes. |
observe | The app's controls with stable refs, like [n12] Button 'Save'. |
locate | Finds controls by role, name or id. |
act | click, double_click, right_click, invoke, fill, press, toggle, select, expand, collapse, focus, scroll_into_view, drag_to, read. |
screenshot | An image of a window, even when it's covered, or of the desktop. |
click, drag, scroll | Act on points of a screenshot, for canvases and games. |
type_text, press_key | Keyboard. mod+s means Ctrl+S on Windows and Cmd+S on a Mac. |
point | Moves the agent's cursor to show you something. |
list_windows, list_agents, status | What's open, who's working, and whether agents are paused. |
Error codes
| Code | Meaning |
|---|---|
NODE_STALE | The control is gone. The agent observes again instead of clicking whatever moved into its place. |
PROTECTED | Your work is at stake. The agent has to ask you. |
PAUSED | You pressed the kill switch. |
LOCKED | The window belongs to another app than the agent's. |
NOT_ACTIONABLE | Disabled, hidden or covered right now. |
UNSUPPORTED | Not possible on this control or system. |
LICENSE_REQUIRED | No license key is active on this computer. |
PERMISSION_REQUIRED | A macOS permission is missing. |
Safety rules
- Accessibility API first, then events sent only to the agent's app. Your pointer and keyboard are borrowed only when nothing else works, only after you've been idle for 0.4 s, for a few milliseconds.
- If an app jumps to the front by itself after an agent acted, Sidehand gives the front back to your window.
- Agents start read-only in windows that may hold your documents.
- Agents never replace text they didn't write.
- Each agent is locked to its own app.
- The kill switch is checked before every action, and stays on after a restart.
- Nothing is sent anywhere. Logs never contain typed text or screenshots.
Troubleshooting
Start with sidehand doctor: it checks each requirement and prints the fix.
| Problem | Fix |
|---|---|
| The AI app doesn't show Sidehand's tools | Run sidehand connect <app> again, then fully quit and reopen the app. |
| No cursor on screen | Cursors hide after 15 minutes without activity and come back with the next action. |
| Clicks don't register in a browser or game | Those ignore background events. Ask the agent to use mode="real"; it waits until you're idle. |
| "runs as administrator" | Windows blocks input into elevated apps from normal ones. |
HOST_UNAVAILABLE | Run sidehand quit-host and try again. |
Still stuck? Write to our contact form and attach the logs (tray or menu-bar icon, "Open logs folder").