Install
Windows
Section titled “Windows”Run this in PowerShell:
irm https://raw.githubusercontent.com/ArcticGizmo/perch/main/install.ps1 | iexThat’s the whole install. It needs no admin rights (Perch lands in %LocalAppData%\Perch\), adds a Start Menu
shortcut and a normal uninstaller under Settings → Apps, and starts Perch in the tray when it’s done. Every
update after this happens in the app: right-click the tray icon → Check for Updates….
What the script does, in order:
- Resolves the latest release.
- Downloads
SHA256SUMS.txtandPerch-win-Setup.exe. - Checks the installer against the manifest, and deletes it rather than run it on any mismatch.
- Runs the installer.
The script is install.ps1 in the repo. Read it
before piping it into your shell, as you should with any installer.
To install a specific version instead of the latest:
$env:PERCH_VERSION = '0.5.38'; irm https://raw.githubusercontent.com/ArcticGizmo/perch/main/install.ps1 | iexBecause PowerShell does the download rather than a browser, nothing gets the mark-of-the-web, so this route never shows the “Windows protected your PC” SmartScreen warning.
Installing by hand
Section titled “Installing by hand”If you’d rather click: download Perch-win-Setup.exe from the
latest release and run it. You get the same install and
the same self-updates.
A browser download is tagged with the mark-of-the-web, so SmartScreen shows the blue “Windows protected your PC” dialog. Click More info → Run anyway, or use the one-liner above to avoid it.
To check the download against the release’s SHA256SUMS.txt yourself:
$want = (Select-String -Path SHA256SUMS.txt -Pattern 'Perch-win-Setup.exe').Line.Split()[0](Get-FileHash Perch-win-Setup.exe -Algorithm SHA256).Hash -eq $want # TruemacOS (Apple Silicon)
Section titled “macOS (Apple Silicon)”- Download the
…-osx-arm64.dmgfrom the latest release. - Open the
.dmgand drag Perch to Applications. - Clear the quarantine flag (below), then launch Perch from Applications.
Every release publishes a SHA256SUMS.txt covering all its files. To check the download first:
shasum -a 256 -c SHA256SUMS.txt --ignore-missing“Perch is damaged and can’t be opened”
Section titled ““Perch is damaged and can’t be opened””The macOS build is not yet code-signed or notarized. macOS tags downloaded unsigned apps with a
com.apple.quarantine flag, and Gatekeeper then refuses to open them with a misleading “damaged” message.
The app isn’t damaged. Remove the flag once, in Terminal:
xattr -cr /Applications/Perch.appThen open Perch normally. You need to do this once per install or update.
If the .dmg itself won’t open, the flag is on the download. Clear it on the disk image first:
xattr -cr ~/Downloads/Perch-osx-arm64.dmgFirst launch on macOS
Section titled “First launch on macOS”Perch runs as a menu-bar app with no Dock icon. On first launch it links perch into ~/.local/bin, wires its
Claude Code hooks, and may show two one-time prompts:
- Notifications, for session alerts.
- Automation (control Terminal), so clicking a session can focus the exact terminal window running it. If you decline, clicking a session just brings the terminal app forward.
