human-presence

Keep macOS "in use" with pointer motion that actually looks human.

Most keep-awake tools jump the cursor one pixel and call it a day. That is a teleport: no path, no acceleration, always the same direction. This one generates real trajectories instead.

human-presence -g 25 90

--------------------------------------------------------------
human-presence   gap 25-90s   speed x1
  display 0: 1512x982 at (0,0)
  display 1: 1920x1080 at (1512,-459)
  Ctrl-C to stop.
--------------------------------------------------------------
10:54:52  micro    20px -> (1185,452)
10:55:33  hop      79px -> (1257,518)
10:55:33  scrolled 4 notches up
10:56:41  travel  612px -> (410,244)

What makes the motion human

Install

Requires macOS and Python 3.9+.

pip install human-presence

From a checkout:

git clone https://github.com/agn-7/human-presence.git
cd human-presence
pip install -e '.[dev]'

Accessibility permission

macOS will not deliver synthetic pointer events until you allow it. Open System Settings → Privacy & Security → Accessibility and enable whichever app runs the command — Terminal, iTerm, or your IDE.

Without permission the events are silently dropped. Use --verify to check: if the idle clock does not reset to 0.0s after an action, permission is missing.

Usage

human-presence [-g MIN MAX] [--speed X] [--hours HH:MM-HH:MM] [--display N]
               [--margin PX] [--no-scroll] [--keys] [--yield-seconds S]
               [--dry-run] [--verify] [--seed N] [-q]

Choosing a gap

Keep the maximum below your screen-sleep setting (System Settings → Lock Screen).

Preview before the real run

human-presence --dry-run -g 3 6

Nothing moves. You only see what it would do.

How idle is detected

CGEventSourceSecondsSinceLastEventType — the same clock the screensaver reads. Keyboard activity counts, not just the mouse. So the tool stays quiet while you are genuinely working, and only acts once you actually stop.

Because that clock is also reset by the tool's own events, a gap is measured from whichever came last: you, or it.

Staying out of the way

• You always win. Touch the mouse and it stands down for --yield-seconds. It also aborts a move mid-flight if the cursor stops tracking the path.
• No hot corners. Every point is clamped into a safe box: inset from all edges, below the menu bar, clear of the corners that trigger Mission Control.
• Multi-display aware. Bounds come from CGGetActiveDisplayList, and the cursor position from CGEventGetLocation, which is correct in global coordinates across stacked or offset monitor layouts.

Run it at login

The repository ships a ready template at packaging/com.agn7.human-presence.plist. Copy it to ~/Library/LaunchAgents/, edit the paths and flags inside, then:

launchctl load ~/Library/LaunchAgents/com.agn7.human-presence.plist
launchctl list | grep human-presence          # confirm it is running
launchctl unload ~/Library/LaunchAgents/com.agn7.human-presence.plist   # stop

Logs go to /tmp/human-presence.log and /tmp/human-presence.err.log. launchd does not expand ~, so use absolute paths if you change them.

Grant Accessibility permission to /usr/local/bin/python3 (or whichever interpreter the plist points at), not to Terminal.

Development

pip install -e '.[dev]'
pytest
ruff check .

Tests cover the movement model, the safe-area maths, and the CLI. The parts that need macOS are marked and skipped elsewhere; the geometry and timing tests run anywhere.

Prior art

The idea comes from carrot69/keep-presence (CC0). This is an independent implementation with a different movement model — trajectories instead of a one-pixel teleport, an idle clock instead of position comparison, and no pynput dependency.

License

MIT. The full text is in the LICENSE file of the source distribution.