Install moshi-hook

moshi-hook is the companion daemon that makes the terminal agent-aware: it installs hook config for Claude Code, Codex, OpenCode, and the rest, owns the local Unix socket agents post events to, serves the host gateway on 127.0.0.1:24543, and keeps the WebSocket to Moshi for approvals and status.

It is a single Go binary with no runtime dependencies, and it runs on macOS and Linux (x86_64 and arm64). Native Windows builds exist as an experimental preview; the stable path on Windows is still WSL.

This page is only about getting the binary onto a host. For what the hooks do once installed — the event matrix, agent config files, and diagnostics — see Agent hooks and Live Activities.

One-line install

The fastest path on any supported host:

$curl -fsSL https://getmoshi.app/install.sh | sh

The script detects your OS and architecture, downloads the matching release from cdn.getmoshi.app, installs moshi-hook into ~/.local/bin, and adds a moshi symlink next to it. If ~/.local/bin is not on your PATH, the script prints the line to add to your shell config.

It also runs a short first-run prompt for discovery and usage settings. Skip it in scripted setups with MOSHI_HOOK_SKIP_FIRST_RUN=1, then run moshi-hook set --first-run later.

Homebrew (macOS)

Homebrew is the better choice on a Mac you use daily: it manages upgrades and can run the daemon under brew services.

$brew tap rjyo/moshi
$brew trust rjyo/moshi
$brew install moshi-hook

Linux and WSL

Use the install script above, then start the daemon as a systemd user service so it survives logout and reboots:

$curl -fsSL https://getmoshi.app/install.sh | sh
$moshi-hook service install
$moshi-hook service status

On WSL, run exactly the same commands inside the distro, and enable the OpenSSH server there (sudo apt install openssh-server) so Moshi can reach the host. If your WSL distro has systemd disabled, run moshi-hook serve from your shell startup or under any process manager instead.

Windows (experimental)

From a normal PowerShell window — no elevation needed:

$powershell -ExecutionPolicy Bypass -c "irm https://getmoshi.app/install.ps1 | iex"

The installer resolves the latest release, verifies the published ZIP against the release checksums, and installs it per-user under %USERPROFILE%\.moshi\packages\standalone\releases. A directory junction at %LOCALAPPDATA%\Programs\Moshi Hook\bin points at the active version and is added to your user PATH; the three newest releases are retained so you can roll back.

Because the preview binaries are not yet Authenticode-signed, SmartScreen may ask you to choose More info → Run anyway.

Open a new PowerShell window, then pair and run the daemon at logon:

$moshi-hook pair --token <token from Moshi>
$moshi-hook install
$moshi-hook service install

On Windows, moshi-hook service install registers a current-user logon entry (HKCU\...\Run) and starts the daemon detached — no elevation, no Windows service. moshi-hook update works the same way as on Linux and replaces the running executable in place.

Known experimental-preview limits: stopping an arbitrary dev-server process gracefully is unavailable (Windows has no SIGTERM equivalent), SSH-origin attribution is unavailable, and Kimi, Qwen, Cursor Agent, the Antigravity CLI, and Gemini CLI are not validated natively.

Manual binary

If you would rather not pipe a script to sh, the same release archives are on the CDN. Pin a version and install directory explicitly:

$curl -fsSL https://getmoshi.app/install.sh | MOSHI_HOOK_VERSION=v0.2.54 INSTALL_DIR=/usr/local/bin sh

Both variables also work with a downloaded copy of the script, so you can read it first and run it yourself:

• MOSHI_HOOK_VERSION — install a specific tag instead of the latest release.
• INSTALL_DIR — where the binary lands. Defaults to ~/.local/bin.
• MOSHI_HOOK_SKIP_FIRST_RUN=1 — skip the interactive first-run settings.

Verify and pair

$moshi-hook version
$moshi-hook status

Then pair the host with your phone. Open Settings → Hooks in Moshi, copy the pairing token, and run:

$moshi-hook pair --token <token from Moshi>
$moshi-hook install

For a first-time host setup, moshi-hook host setup prints an Easy Pair QR that also creates the SSH connection — see Install and prepare a host.

Keep it running

The daemon must be up for agent events, approvals, and Chat View. Pick the one that matches how you installed it:

# Homebrew on macOS
$brew services start moshi-hook
# systemd on Linux or WSL, logon startup on Windows
$moshi-hook service install
# anything else — foreground, under your own supervisor
$moshi-hook serve

moshi-hook service install covers systemd on Linux and logon startup on Windows; on a manual macOS install, run moshi-hook serve or switch to Homebrew.

Update

Manual and script installs update themselves in place:

$moshi-hook update
$moshi-hook update --version v0.2.54

Homebrew installs upgrade through brew instead — moshi-hook update is not the right tool there:

$brew update
$brew upgrade moshi-hook
$brew services restart moshi-hook

Pairing and installed agent hooks survive an upgrade, so there is no need to re-pair or re-run moshi-hook install.

Uninstall

$moshi-hook uninstall
$moshi-hook unpair
# then remove the binary itself
$moshi-hook service uninstall
$brew uninstall moshi-hook
$rm ~/.local/bin/moshi-hook ~/.local/bin/moshi

moshi-hook uninstall removes only the Moshi-owned entries from agent config files and leaves your own hooks alone.

If the install fails

The install script and Homebrew both pull binaries from cdn.getmoshi.app. On rare networks Cloudflare serves a bot challenge to curl and the download returns HTTP 403 — Troubleshooting covers that case, along with the not installed dot and gateway checks.