Hook settings

moshi-hook keeps a small set of host-level settings for background work, notifications, updates, the Files browser, and Browser Preview discovery. List the current values and config path at any time:

moshi-hook set

Use kebab-case names with the CLI. Boolean settings accept on and off; the config file stores their snake-case equivalents under [gateway]. Show a single setting by naming it without a value, for example moshi-hook set auto-update.

Change settings from the app

Most switches are also in Moshi. On Home, tap Hooks at the right end of the Connections header (it shows status dots when Show hook status is on), pick a host, and use its Options section:

• Always-on discovery, Dev server scan (scan-ports as a simple on/off), Usage collection, Quiet nested agents, Quiet while unlocked (macOS hosts), Quiet outside a multiplexer, Inline visuals, Background git fetch, and mata (macOS hosts).
• Install updates: Ask, Auto, or Off, the same as auto-update.
• End-to-end encryption, the same as moshi-hook e2ee enable and disable.

The app talks to the daemon over your SSH connection, never through Moshi's servers. When a saved option needs a restart, the sheet says so and offers Restart moshi-hook, which restarts the daemon for you once no approval, prompt, or update is in progress. If the daemon can't restart itself, the sheet shows the command to run on the host instead.

Port lists, the usage polling interval, proxy, tmux-sockets, files-exclude, files-roots, allowed-hosts, and allow-other-users are CLI-only.

Settings at a glance

After changing a setting marked Yes, restart the daemon:

moshi-hook service restart

brew services restart moshi-hook on macOS with Homebrew and systemctl --user restart moshi-hook.service on Linux with systemd work too. If you run moshi-hook serve yourself, stop and start that process instead. The other settings apply on their own: scan-ports on the next discovery refresh, files-exclude and files-roots the next time a folder is opened, tmux-sockets the next time Moshi reads the session list, rex-server within a few seconds, git-background-fetch within five minutes, auto-update at the next release check, suppress-push-without-mux on the next event, and inline-visuals immediately.

End-to-end encryption has its own commands, moshi-hook e2ee enable and friends, and takes effect without a restart. See End-to-end encryption.

Background discovery

Keep discovery running even when a phone is not currently attached:

moshi-hook set always-on-discovery on

Turn it off to pause those idle server and simulator scans. Discovery still runs when Moshi actively subscribes, but the first result after reconnecting may take a refresh cycle.

Usage collection

Background usage collection keeps the usage rings in Moshi current. By default it polls once a minute:

moshi-hook set usage-collection on

Poll less often by passing an interval of at least one minute. on later keeps the interval you chose:

moshi-hook set usage-collection 5m

Turn it off to stop background rate-limit polling and snapshot uploads from this host:

moshi-hook set usage-collection off

On-demand moshi-hook usage still reads local snapshots, and moshi-hook usage --sync can still upload them explicitly. See Agents & Usages.

Nested-agent events

An agent can launch another supported agent as a child process. To keep those nested runs out of Moshi:

moshi-hook set suppress-nested-agent-push on

This suppresses the nested agent's event entirely—not just its notification banner. Its inbox updates, completion events, and approval requests will not reach the phone. Leave this off if a nested agent may stop and wait for your approval.

Silent push while a Mac is unlocked

On macOS, keep agent events flowing to the inbox while silencing visible notification banners whenever the local console is unlocked:

moshi-hook set suppress-push-while-unlocked on

This affects visible approval, completion, and error pushes. The event is still published to Moshi; only its notification is marked silent. Lock state is only a signal that the Mac is unlocked, not proof that somebody is looking at it, so the setting is off by default. If macOS lock state cannot be read, moshi-hook leaves the push enabled. Questions from moshi-hook ask still push.

Silent push outside a multiplexer

An agent started in a plain terminal, outside tmux, Herdr, Zellij, or Rex, has no pane Moshi can open from a notification. By default its events still reach the inbox, but their pushes are silent. To get visible notifications for those agents too:

moshi-hook set suppress-push-without-mux off

Either way, approvals you can answer from the phone, and moshi-hook notify and ask, still alert. The change applies to the next event without a restart.

Inline visuals

Claude Code and Codex can answer with a chart, diagram, table, or mockup that Moshi shows right in the chat. moshi-hook installs a small moshi-visuals skill that teaches them how, wherever their global hooks are installed. It's on by default. Turn it off to remove the skill:

moshi-hook set inline-visuals off

The change applies immediately: on writes the skill, off removes it, and moshi-hook install and uninstall keep it in step. Project-local installs (install --local) never get the skill, and a moshi-visuals folder that Moshi didn't create is left alone. See Inline visuals.

Background git fetch

To keep "behind" counts current, moshi-hook can fetch the upstream of repositories shown in the app every 5 minutes:

moshi-hook set git-background-fetch on

It's off by default because a background fetch uses your git credentials and can trigger SSH-agent or credential prompts. The change applies within five minutes without a restart.

Automatic updates

The daemon checks for new moshi-hook releases every 6 hours. Since 0.4.34 it installs them by default (through brew upgrade for Homebrew installs) and restarts itself once no approval is pending. To only be told about new releases, or to stop checking:

moshi-hook set auto-update ask
moshi-hook set auto-update off

With ask, Moshi flags the host, and its hooks sheet can check again or update with one tap. If you chose ask or off before 0.4.34, that choice is kept. moshi-hook set auto-update auto switches automatic installs back on. See Install moshi-hook for manual updates.

Proxy

If the host can only reach the internet through a proxy, send the daemon's traffic to Moshi (agent events, the phone connection, and update checks) through it:

moshi-hook set proxy http://proxy.example.com:8080
moshi-hook set proxy socks5://127.0.0.1:1080

A bare host:port means an HTTP proxy. Unlike HTTPS_PROXY, the setting survives brew services restart and brew upgrade, which rewrite the macOS service definition. Other values:

• env (default): use only the daemon's own HTTP_PROXY, HTTPS_PROXY, and NO_PROXY.
• system: use the macOS system proxy.
• off: connect directly, even when HTTPS_PROXY is set.

Local traffic never goes through the proxy. A password in the URL is hidden in moshi-hook set and doctor output, and moshi-hook doctor shows which proxy is in use. Restart the daemon so its open connection to Moshi moves to the new route.

Browser Preview ports

By default, Browser Preview considers every eligible loopback listener and uses conservative heuristics to avoid probing unrelated services:

moshi-hook set scan-ports all

Restrict discovery to ports you trust as HTTP servers:

moshi-hook set scan-ports 3000,5173,8000

Inclusive ranges work too, which is the simplest way to keep unrelated local services out of discovery — list the range you develop in and nothing else is probed:

moshi-hook set scan-ports 3000,8000-8010

An explicit list is authoritative, so it can include high-numbered ports that broad discovery would normally skip. Only loopback-reachable listeners are eligible. Disable HTTP probing completely with:

moshi-hook set scan-ports none

This only controls Browser Preview's HTTP probes; it does not stop the underlying processes or change which addresses they bind. Turning Dev server scan off in the app is the same as none; turning it back on scans every port, and a port list set from the CLI stays as it is. See Browser Preview for the app-side workflow.

Extra tmux servers

tmux servers started with tmux -L <name> show up in the session picker on their own. Servers started with tmux -S <path> need their socket listed:

moshi-hook set tmux-sockets ~/.tmux/agents.sock,/tmp/work.sock

Separate paths with commas. none clears the list. See tmux.

Rex server

Shells inside Rex have REX_SERVER set, but the moshi-hook daemon usually doesn't, so the daemon can miss a server that those shells reach. If Moshi lists no Rex sessions, name the server's socket. This needs moshi-hook 0.4.47 or newer:

moshi-hook set rex-server ~/.local/state/rex/run/server.sock

To find the socket, run echo $REX_SERVER in a Rex block. The setting takes that value as it is, or a plain path. default goes back to Rex's usual locations. A REX_SERVER in the daemon's own environment wins over this setting. See Rex.

Files browser folders

The Files browser hides version-control metadata, dependency trees, and caches by default: .git, .hg, .svn, .DS_Store, node_modules, .pnpm-store, .yarn, __pycache__, .venv, venv, .mypy_cache, .pytest_cache, .ruff_cache, .next, .nuxt, .svelte-kit, .turbo, .parcel-cache, .gradle, Pods, and DerivedData. Other gitignored files are listed, shown muted. Replace the list with your own names or globs:

moshi-hook set files-exclude node_modules,.git,*.pyc

Patterns match a single file or folder name, not a path. default restores the built-in list, and none lists everything except .git.

The Files browser opens folders inside your home folder, plus the working folder of a running agent session without any setup. To open other folders outside home, such as WSL projects on /mnt/c, list them:

moshi-hook set files-roots /mnt/c/Users/me/proj

Use absolute paths separated by commas; ~ expands to your home folder. A filesystem root such as / is refused, and none clears the list.

Web client hostnames and other accounts

The daemon's local servers — the gateway the app reaches through SSH, and the web client you start with bare moshi — only accept requests from your own Moshi clients. If you open the web client by a hostname, such as a Cloudflare Tunnel, a .local name, or a reverse proxy, allow that name:

moshi-hook set allowed-hosts moshi.example.com,mac.local

Give hostnames only, without a scheme or port. Until the name is allowed, the page shows a 403 that names the exact command. Opening it by IP address, as with moshi --listen 0.0.0.0:24544, needs no setting. Restart the daemon and any running web client afterwards. none clears the list.

If the daemon runs as a different user than your clients, for example under sudo, let other accounts on the machine connect:

moshi-hook set allow-other-users on

Use it only on machines where every account is trusted. See Security and sync.

First-run prompt

The install script offers the main background and notification switches during setup — always-on-discovery, usage-collection, suppress-nested-agent-push, suppress-push-while-unlocked (macOS), suppress-push-without-mux, and inline-visuals — with their defaults pre-selected. Reopen that prompt manually with:

moshi-hook set --first-run

Homebrew does not run an installer prompt. The defaults apply until an interactive host setup, serve, pair, or install command offers it, or until you run set --first-run yourself.

Edit the config file directly

The CLI preserves comments and unrelated keys in ~/.config/moshi/config.toml. The defaults, written out, are:

[gateway]
always_on_discovery = true
usage_collection = true
suppress_nested_agent_push = false
suppress_push_while_unlocked = false
suppress_push_without_mux = true
inline_visuals = true
git_background_fetch = false
mata = true
auto_update = "auto"
proxy = "env"
scan_ports = "all"
tmux_sockets = []
files_exclude = "default"
files_roots = []
allowed_hosts = []
allow_other_users = false

[rex]
server = "default"

A custom usage interval is stored as usage_poll_interval = "5m". For a fixed Browser Preview allowlist, use a TOML array such as scan_ports = [3000, 5173, 8000]. Ranges are written as quoted strings — scan_ports = [3000, "8000-8010"] — and the CLI stores them that way too. An empty array disables HTTP probing, just like moshi-hook set scan-ports none. The other list settings take string arrays, such as files_roots = ["/mnt/c/Users/me/proj"].

Related one-shot flags

Persistent settings above are different from command flags. The daemon also accepts moshi-hook serve --gateway-listen <address> to override its local gateway bind address for that run. Every command accepts --verbose for debug logs and --base-url for a non-default Moshi API endpoint. Run moshi-hook <command> --help for that command's complete one-shot flag list.