canaryd

A quiet health monitor for your Mac.
It detects heat and stalled apps, then recovers them without taking your focus.

Install · Usage · How it works · Development

Canaryd is a local macOS watchdog. It uses exact Apple Silicon temperature data, macOS responsiveness state, and a reversible clipboard probe to find problems that a simple process check can miss.

• Watch heat. Detect CPU or GPU temperatures at or above 70°C and show the processes that correlate with the load.
• Recover stalled apps. Confirm that a GUI app is not responding before a controlled restart.
• Verify CleanClip. Check that CleanClip records new clipboard items, not only that its process exists.
• Stay quiet. Use background restarts and Notification Center. Do not open a foreground alert or take input focus.
• Keep data local. Store state, events, and logs on the Mac.

Status at a glance

Run canaryd status to see health, recent recovery events, pending app hangs, and thermal pressure.

The screenshot contains example values. Process names, temperatures, and events come from your Mac.

Install

Install with an AI agent

Give this prompt to Codex, Claude Code, Cursor, or another coding agent:

Read https://raw.githubusercontent.com/ThaddeusJiang/canaryd/main/SKILL.md and follow its instructions to install or update Canaryd on this Mac.

Requirements

• macOS on Apple Silicon or Intel
• Xcode Command Line Tools for the built-in notification helper
• macmon 0.8.0 for exact CPU and GPU temperatures on Apple Silicon

The GitHub Release executable includes Erlang and Elixir. A source or Hex installation needs Elixir 1.15 or later.

Install the system tools:

xcode-select -p >/dev/null || xcode-select --install

if [ "$(uname -m)" = "arm64" ]; then
  brew install macmon
  brew pin macmon
  macmon --version
fi

On Apple Silicon, the last command must print macmon 0.8.0. Canaryd rejects another version until its JSON schema is verified. Intel Macs do not provide exact CPU and GPU sensor temperatures.

Install from GitHub Releases

Install the latest stable release:

curl -fsSL https://github.com/ThaddeusJiang/canaryd/releases/latest/download/install.sh | bash

The installer selects the Mac architecture, verifies SHA-256, and installs canaryd in ~/.local/bin. It adds that directory to the current shell profile when necessary. Restart the shell or run the source command that the installer prints. You can then use canaryd from any directory.

Install a downloaded archive

Open the latest GitHub Release. Download checksums-sha256.txt and the archive for the Mac:

Verify and install the downloaded archive:

cd "$HOME/Downloads"

if [ "$(uname -m)" = "arm64" ]; then
  archive="canaryd-aarch64-apple-darwin.tar.gz"
else
  archive="canaryd-x86_64-apple-darwin.tar.gz"
fi

grep " $archive\$" checksums-sha256.txt | shasum -a 256 -c -
tar -xzf "$archive"
mkdir -p "$HOME/.local/bin"

# Run this only after the checksum succeeds. The first releases are not notarized.
xattr -d com.apple.quarantine canaryd 2>/dev/null || true
install -m 755 canaryd "$HOME/.local/bin/canaryd"

Add the install directory to PATH if the shell cannot find canaryd:

export PATH="$HOME/.local/bin:$PATH"

Add that line to the shell profile to keep the setting.

The first GitHub releases use ad hoc code signing. They do not use Apple notarization. The checksum verifies that the download matches the release asset. It does not provide an Apple developer identity.

Install the current source

Use this method for the features documented in this repository:

git clone https://github.com/ThaddeusJiang/canaryd.git
cd canaryd
mix deps.get
mix escript.build
mix escript.install --force ./canaryd

Install the published release

The Hex package remains available for systems that already have Elixir:

mix escript.install hex canaryd 0.1.0

Add the Mix escript directory to PATH if the shell cannot find canaryd:

export PATH="$HOME/.mix/escripts:$PATH"

Add that line to the shell profile to keep the setting.

First run

canaryd status

The first command installs two launchd agents:

Every command verifies these agents. If an agent is missing, Canaryd creates it again. You do not need to manage plist files.

Usage

Examples:

canaryd check
canaryd history thermal
canaryd history apps

How it works

Canaryd applies a confirmation and cooldown policy before it changes another app.

Safety rules

• Canaryd never treats battery temperature as CPU or GPU temperature.
• A user clipboard change always takes priority over probe restoration.
• A third-party GUI app must fail two consecutive checks before restart.
• Apple apps, system daemons, and unsafe helper processes do not get automatic actions.
• Each app has a one-hour restart or prompt cooldown.
• Automatic termination can discard unsaved data in a stalled app.

When the Mac is idle for more than 30 minutes, Canaryd skips the CleanClip functional probe. It still checks the system and GUI responsiveness.

Local data

Canaryd stores all runtime data in:

~/Library/Application Support/canaryd/
├── state.dets
├── events.dets
├── stdout.log
└── stderr.log

state.dets contains the latest state-machine snapshot. events.dets contains the event history for app, thermal, system, and probe actions. The log files contain launchd output.

Uninstall

Remove the launchd agents and the notification helper:

canaryd uninstall

To remove the saved state and logs too:

rm -r "$HOME/Library/Application Support/canaryd"

Development

git clone https://github.com/ThaddeusJiang/canaryd.git
cd canaryd
mix deps.get
mix test
mix escript.build

Build the native single executable with Zig 0.16.0:

mise install zig@0.16.0
BURRITO_TARGET=macos_arm64 MIX_ENV=prod mise exec zig@0.16.0 -- mix release --overwrite
./burrito_out/canaryd_macos_arm64 --version

The project uses pure Elixir/OTP, DETS storage, launchd, and a small Swift notification helper.

License

MIT