{"id":"paseo-screen","repo":"kevguy/paseo-screen","url":"https://github.com/kevguy/paseo-screen","package":"@kevlai22/paseo-screen","npm":{"package":"@kevlai22/paseo-screen","version":"0.1.1","integrity":"sha512-xq7N9uEtfCKSRDWuI06HhNmtRxc8spwzZDmi2RYmVeYiP6flHWkqxrppPp45CFdBhFweIFTJhvW9DkiB/QqgmA==","publishedAt":"2026-10-20T19:57:35.647Z","downloadsLast30Days":0},"name":"paseo-screen","description":"See and control the Paseo host Mac screen from any paired Paseo client, over the existing Paseo connection.","categories":["productivity","monitoring"],"platforms":["macos"],"caveats":["The host must be a Mac on macOS 14 or later with the Xcode command line tools; any Paseo client can view it.","Someone at the host must grant Paseo Screen Recording and Accessibility once, then reopen Paseo.","Frames are polled JPEGs at roughly 5 to 15 fps depending on the network, so it is not smooth video.","Anyone paired with the host can see and control its screen while the plugin is enabled.","Clipboard sync is text only and works on desktop and web clients."],"images":["https://raw.githubusercontent.com/kevguy/paseo-screen/1df9050d3721d927aa73655ad2cb4b4b53f42db9/images/desktop-viewer.jpg","https://raw.githubusercontent.com/kevguy/paseo-screen/1df9050d3721d927aa73655ad2cb4b4b53f42db9/images/laptop-client.jpg","https://raw.githubusercontent.com/kevguy/paseo-screen/1df9050d3721d927aa73655ad2cb4b4b53f42db9/images/remote-editing.jpg"],"themes":[],"health":{"manifestValid":true,"hasReadme":true,"hasLicense":true,"hasTests":true,"hasTypecheckScript":true,"updatedRecently":true},"scannedAt":"2026-10-20T21:32:56.348Z","addedAt":"2026-10-20T16:53:34Z","npmSecurity":{"status":"passed","blockingFindings":0,"advisoryFindings":0,"scannedAt":"2026-10-20T21:32:33.368Z","version":"0.1.1","integrity":"sha512-xq7N9uEtfCKSRDWuI06HhNmtRxc8spwzZDmi2RYmVeYiP6flHWkqxrppPp45CFdBhFweIFTJhvW9DkiB/QqgmA=="},"version":"0.1.1","security":{"status":"passed","blockingFindings":0,"advisoryFindings":0,"scannedAt":"2026-10-20T21:32:33.368Z","commit":"1df9050d3721d927aa73655ad2cb4b4b53f42db9"},"author":"Kevin Lai","license":"MIT","paseoVersionRequirement":">=0.12.0","descriptionNodes":[{"type":"text","text":"See and control the Paseo host Mac screen from any paired Paseo client, over the existing Paseo connection."}],"caveatNodes":[[{"type":"text","text":"The host must be a Mac on macOS 14 or later with the Xcode command line tools; any Paseo client can view it."}],[{"type":"text","text":"Someone at the host must grant Paseo Screen Recording and Accessibility once, then reopen Paseo."}],[{"type":"text","text":"Frames are polled JPEGs at roughly 5 to 15 fps depending on the network, so it is not smooth video."}],[{"type":"text","text":"Anyone paired with the host can see and control its screen while the plugin is enabled."}],[{"type":"text","text":"Clipboard sync is text only and works on desktop and web clients."}]],"manifest":{"id":"paseo-screen","name":"Host screen","icon":"assets/icon.png","media":["images/laptop-client.jpg","images/desktop-viewer.jpg","images/remote-editing.jpg"],"requirements":{"paseo":">=0.12.0"}},"repoMeta":{"stars":0,"defaultBranch":"main","pushedAt":"2026-10-20T19:38:09Z"},"owner":{"login":"kevguy","avatarUrl":"https://avatars.githubusercontent.com/u/13964463?v=4"},"installNotesHtml":"
    \n
  1. \n

    Enable plugins on the host by setting \"pluginsEnabled\": true in ~/.paseo/config.json, then run paseo reload.

    \n
    2. \n
  2. \n

    Install the plugin on the host:

    \n
    paseo plugin install npm:@kevlai22/paseo-screen\n# or from GitHub\npaseo plugin install git:kevguy/paseo-screen\n
    \n
    3. \n
  3. \n

    On the host Mac, open System Settings → Privacy & Security and turn on Paseo under both Screen Recording and Accessibility. Quit and reopen Paseo.

    \n
    4. \n
  4. \n

    In any Paseo client, open Screen · host name from the sidebar, or search \"host screen\" in the command center.

    \n
    5. \n
\n

If a permission is missing, the viewer says which one and offers a button that shows the macOS prompt on the host. Someone has to be at the host Mac to approve it once.

\n

macOS gives these permissions to the app that started the Paseo daemon. That is normally the Paseo desktop app. If you run the daemon some other way, for example paseo start from a terminal, grant the permissions to that app (such as Terminal) instead.

","limitationsNotesHtml":"","readmeText":"# Host screen for Paseo\n\nA [Paseo](https://paseo.sh) plugin that lets you see and control the screen of the Mac running your Paseo daemon, from any paired Paseo client: the desktop app, the web app or your phone. Think of a small TeamViewer that rides on the Paseo connection you already have, relay included, so there is no port forwarding, VPN, VNC or extra account.\n\nIt was built for the moments when an agent on a remote Mac needs a human: watching a Playwright run, clicking through a permission dialog, or checking what is actually on screen.\n\n![Controlling the host Mac from Paseo on a laptop](images/laptop-client.jpg)\n\n## Features\n\n- Live view of the host's screen, sized to your viewer, at roughly 5 to 15 frames per second depending on the network.\n- Mouse and keyboard control: click, double-click, right-click, drag, scroll and type.\n- A key bar for shortcuts your own computer keeps for itself: ⌘Tab, ⌘Space, ⌘W, ⌘Q, switching Spaces (⌃←/⌃→), Mission Control and App windows.\n- Two-way text clipboard on desktop and web clients. ⌘V pastes your clipboard on the host, and ⌘C on the host copies back to you.\n- Multiple displays: each one is listed by name, the last choice is remembered, and a drag that leaves the picture continues onto the neighbouring display.\n- Phones: tap to click, long-press to right-click, pinch to zoom, drag to pan, and a Rotate button that turns the picture sideways.\n- Wakes the host's display when you open the viewer, and shows the lock screen if the Mac is locked so you can type your password to unlock it.\n- View-only mode, and Fast / Balanced / Sharp quality presets.\n\n![Viewing the host's second display](images/desktop-viewer.jpg)\n\n![Typing and selecting text on the host from another computer](images/remote-editing.jpg)\n\n## Requirements\n\n- A Mac host running macOS 14 or later, with the Xcode command line tools (`xcode-select --install`). The native helper is compiled with `swiftc` the first time it is used.\n- Paseo 0.12 or later, with plugins enabled on the host.\n- Any Paseo client paired with that host.\n\n## Install\n\n1. Enable plugins on the host by setting `\"pluginsEnabled\": true` in `~/.paseo/config.json`, then run `paseo reload`.\n2. Install the plugin on the host:\n\n ```bash\n paseo plugin install npm:@kevlai22/paseo-screen\n # or from GitHub\n paseo plugin install git:kevguy/paseo-screen\n ```\n\n3. On the host Mac, open System Settings → Privacy & Security and turn on **Paseo** under both **Screen Recording** and **Accessibility**. Quit and reopen Paseo.\n4. In any Paseo client, open **Screen · _host name_** from the sidebar, or search \"host screen\" in the command center.\n\nIf a permission is missing, the viewer says which one and offers a button that shows the macOS prompt on the host. Someone has to be at the host Mac to approve it once.\n\nmacOS gives these permissions to the app that started the Paseo daemon. That is normally the Paseo desktop app. If you run the daemon some other way, for example `paseo start` from a terminal, grant the permissions to that app (such as Terminal) instead.\n\n## How it works\n\n```\nPaseo client (laptop, web, phone) Host Mac (Paseo daemon)\n Host screen view ── plugin RPC over Paseo relay ──▶ plugin server\n - polls screen.frame, two in flight ├─ helper #1: ScreenCaptureKit → JPEG\n - sends screen.input batches └─ helper #2: CGEvent mouse and keyboard\n```\n\n- `helper/main.swift` is a small native helper speaking line-delimited JSON. The plugin server embeds its source, compiles it into `~/Library/Caches/paseo-screen//`, and runs two copies so input never waits behind a frame capture.\n- macOS grants Screen Recording and Accessibility to Paseo as the responsible app, so rebuilding the helper does not need new permissions.\n- Frames are JPEGs sized to the viewer. Unchanged frames come back without image data.\n- The RPCs are defined in `shared/rpc.ts`: `screen.status`, `screen.request-permissions`, `screen.frame`, `screen.input`, `screen.clipboard` and `screen.choose-display`.\n\n## Security\n\nAnyone paired with the host can see and control its screen while the plugin is enabled. That is the same trust that pairing already grants for running agents and terminals on that machine. Traffic stays inside the Paseo connection; the plugin opens no ports and talks to no other service. View-only mode is a setting in each viewer, not a lock on the host: any paired client can still send input. Turn the plugin off with `paseo plugin disable paseo-screen` when you don't need it.\n\n## Limitations\n\n- Only Mac hosts are supported. Any Paseo client can view.\n- It is frame polling, not video. Fast motion looks choppy, and the frame rate depends on your link to the Paseo relay.\n- Granting the two macOS permissions needs someone physically at the host once.\n- The plugin doesn't stop the host from sleeping or locking on its own schedule. Opening the viewer, using the mouse or keyboard on the picture, or the **Wake display** button wakes the display, and you unlock it by typing your password. Touch ID isn't available remotely.\n- Shortcuts your own computer or the Paseo app handle first (⌘Tab, ⌘Space, ⌘W, ⌘Q) need the key bar buttons.\n- Clipboard sync is text only, and only on desktop and web clients.\n- Keys are sent by physical position, so both computers should use the same keyboard layout.\n- No audio and no file transfer.\n\n## Development\n\n```bash\nnpm install\nnpm run typecheck # also re-embeds helper/main.swift into server/helper-source.generated.ts\nnpm test # rotate/zoom/pan math for the touch viewer\npaseo plugin install \"$PWD\" # once, from a checkout\npaseo plugin reload paseo-screen # after changes\npaseo plugin logs paseo-screen\n```\n\nAfter editing `helper/main.swift`, run `npm run embed` (or `npm run typecheck`). The plugin bundle runs from memory, so the server can't read files next to itself and the helper source has to be embedded.\n\n`scripts/` also has tools that call the plugin through a running daemon, using Paseo's CLI internals from an extracted copy of the Paseo app (`npx @electron/asar extract /Applications/Paseo.app/Contents/Resources/app.asar `):\n\n- `rpc-probe.mjs [json]` calls one RPC and saves frames to `build/probe-frame.jpg`.\n- `frame-bench.mjs` and `pipeline-bench.mjs` measure frame latency and throughput, locally or through the relay.\n- `compile-check.mjs` bundles the plugin with Paseo's own plugin compiler.\n\n## License\n\n[MIT](LICENSE)\n"}