# SidecarKeeper

> SidecarKeeper is a free, open-source (MIT) macOS utility that automatically reconnects Apple Sidecar, so an iPad keeps working as a Mac's second display after display sleep, screen lock, lid close, or a dropped link. It avoids the "Unable to connect to iPad" notification spam that naive retry scripts cause, by only attempting a connection when one can succeed.

Key facts:

- Platform: macOS 14.2 or newer, universal binary for Apple silicon and Intel (tested on Apple silicon). The release install needs nothing but macOS: no Xcode, no git, no sudo, no kernel extension, no privacy permissions.
- Install (unlock the iPad first): `/bin/bash -c "$(curl -fsSL https://github.com/EMOEMOJAI/SidecarKeeper/releases/latest/download/install.sh)"`. Non-interactive form with options: append ` sk --device "iPad name"` after the closing quote. With Homebrew: `brew install emoemojai/tap/sidecarkeeper && brew services start sidecarkeeper`. Alternative: download SidecarKeeper.tar.gz from the latest release and run its install.sh, or git clone and run ./install.sh to build from source. Uninstall with `~/.sidecarkeeper/uninstall.sh`.
- How it works: a per-user LaunchAgent runs a small Swift daemon. Every 15 seconds, and on wake or unlock events, it calls SidecarLauncher's connect only if the user has not paused it, the screens are awake, the session is unlocked, the laptop lid is open, and the iPad is reachable. Failures back off from 30 seconds to 5 minutes.
- Commands: `sidecar-keeper status`, `sidecar-keeper pause`, `sidecar-keeper resume`.
- Settings file: `~/Library/Application Support/SidecarKeeper/config`, one `name = value` per line (`device = My iPad`, `wired = true`, `interval`, `settle`, `timeout`, `usb-match`). Create it with `sidecar-keeper config --init`, inspect with `sidecar-keeper config`, then restart the watcher. This is how a `brew services` install is configured. Command-line flags win over the file.
- Options: `--device NAME`, `--wired` (experimental, USB cable only), `--interval`, `--settle`, `--timeout`, `--log`.
- Hard limits set by macOS, not by this tool: Sidecar always drops when the built-in display turns off, and Sidecar cannot run with a MacBook lid closed (clamshell mode, error -501). SidecarKeeper reconnects within seconds once the display is back.
- Built on Ocasio-J/SidecarLauncher (MIT), which drives Apple's private SidecarCore framework. SidecarKeeper builds it from source at a pinned commit.

## Docs

- [README](https://github.com/EMOEMOJAI/SidecarKeeper/blob/main/README.md): overview, install, daily commands, limits
- [User guide](https://github.com/EMOEMOJAI/SidecarKeeper/blob/main/docs/guide.md): installation, configuration, wired mode, troubleshooting and removal
- [Contributing](https://github.com/EMOEMOJAI/SidecarKeeper/blob/main/CONTRIBUTING.md): building, testing and releases
- [Website](https://emoemojai.github.io/SidecarKeeper/): overview and quick start
- [Changelog](https://github.com/EMOEMOJAI/SidecarKeeper/blob/main/CHANGELOG.md): release history
- [AGENTS.md](https://github.com/EMOEMOJAI/SidecarKeeper/blob/main/AGENTS.md): how to build, test and safely modify the project

## Source

- [Watcher source](https://github.com/EMOEMOJAI/SidecarKeeper/blob/main/Sources/SidecarKeeper/main.swift): the whole daemon, one Swift file
- [Installer](https://github.com/EMOEMOJAI/SidecarKeeper/blob/main/install.sh)

## Optional

- [SidecarLauncher upstream](https://github.com/Ocasio-J/SidecarLauncher): the CLI that performs the actual connect
- [Apple: Use an iPad as a second display for a Mac](https://support.apple.com/en-us/102597)