On This Page
Install hs
One time only. From your second task on, skip this step and go straight to Step 3.
Prerequisites
What you need
- Docker Desktop, installed and running.
- git. Check with git --version. Windows: install Git for Windows.
- SSH access to GitHub, so you can clone your task repo.
- Your task key and assistant key from HAI (Step 1). You paste them in Step 3.
- Optional: the GitHub CLI (gh), logged in. With it, hs opens your pull request for you; without it, hs prints a link to click.
Download
Download the file for your machine. That one file is also the installer. Current version: 4.0.2.
| Your machine | File | |
|---|---|---|
| Mac, Apple Silicon (M1 to M4) | claude-harness-4.0.2-darwin-arm64 | Download |
| Mac, Intel | claude-harness-4.0.2-darwin-amd64 | Download |
| Linux, x86_64 | claude-harness-4.0.2-linux-amd64 | Download |
| Linux, ARM | claude-harness-4.0.2-linux-arm64 | Download |
| Windows | claude-harness-4.0.2-windows-amd64.exe | Download |
Checksums: SHA256SUMS
Not sure? On macOS or Linux run uname -sm. Darwin arm64 is darwin-arm64, Darwin x86_64 is darwin-amd64, Linux x86_64 is linux-amd64, Linux aarch64 is linux-arm64.
One manual download only. After this, hs updates itself at your next command whenever a new release ships.
Install
macOS / Linux
cd ~/Downloads
xattr -d com.apple.quarantine claude-harness-4.0.2-darwin-arm64 # macOS only
chmod +x claude-harness-4.0.2-darwin-arm64
./claude-harness-4.0.2-darwin-arm64 installmacOS asks once whether Terminal may access your Downloads folder. Click Allow; if you decline, the xattr line fails with Operation not permitted.
Windows (PowerShell)
cd ~\Downloads
.\claude-harness-4.0.2-windows-amd64.exe installmacOS: remove the quarantine flag first
Anything a browser downloads is tagged com.apple.quarantine, and macOS then kills an unsigned binary silently, with no error. The xattr line above clears it. Run it before chmod.
Put it on your PATH
install copies the binary to ~/.local/bin/hs on macOS and Linux, and to %LOCALAPPDATA%\Programs\hs\hs.exe on Windows. If hs is not found afterwards, add that folder to your PATH:
# macOS (zsh)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
# Linux (bash)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrcWindows: Settings, Edit environment variables for your account, add %LOCALAPPDATA%\Programs\hs to Path.
Check it works
hs --version # prints the version and build
hs doctor # checks Docker, git, the registry, local state and clipboardhs doctor is the first thing to run whenever something looks wrong later.
Troubleshooting
| Symptom | Fix |
|---|---|
| xattr says "Operation not permitted" (macOS) | Terminal is blocked from your Downloads folder. Open System Settings, Privacy & Security, Files and Folders, find Terminal and turn on Downloads Folder (or give Terminal Full Disk Access), then quit and reopen Terminal and run the xattr line again. If it still fails, move the file out of Downloads first: mkdir -p ~/hs && mv ~/Downloads/claude-harness-4.0.2-darwin-arm64 ~/hs/ && cd ~/hs, then run the xattr, chmod and install lines from there. |
| xattr still fails after that (macOS) | Run xattr -c claude-harness-4.0.2-darwin-arm64 to clear every attribute. If macOS then kills the binary silently when you run install, open System Settings, Privacy & Security, scroll to the notice about the blocked file, click Open Anyway, and run the install line again. |
| The binary dies instantly with no output (macOS) | Run xattr -d com.apple.quarantine <file> and try again |
| command not found: hs | The install folder is not on your PATH, see above |
| Docker is not running | Start Docker Desktop and wait for the whale icon |
| registry unavailable, 404 | Harmless, the run continues |
| permission denied when running the binary | chmod +x <file> |
| An old boson, claude-maven or claude-gradle still runs | Run hs uninstall once to clear the old names, then open a new terminal. |
| Running low on disk | docker system prune -a reclaims images and build cache |