moshterm

~ moshterm-hook

The companion

moshterm-hook is a small program that runs on the computer your agents use. It is what turns a terminal into something that knows an agent is waiting.

What it adds

  • Approvals: an agent's permission prompt arrives on your phone, and your answer goes back to it.
  • The Inbox and notifications: which session needs you, which are working, which are done.
  • Chat View: the agent's transcript, read on your computer and shown as a conversation.
  • Jump To and the session picker's view of tmux, Zellij and Herdr.
  • Diffs and file browsing for the folder the terminal is in.

Without it moshterm is still a complete Mosh, Eternal Terminal and SSH terminal.

The easy way

Connect to the computer from the app. If the companion isn't there, moshterm offers to install it over that connection; say yes and it does the rest. Later, the app keeps an older companion up to date the same way when you connect.

By hand

On macOS, Linux or WSL:

# installs to ~/.local/bin and starts the background servicecurl -fsSL https://mickmosh-relay.mick-fb5.workers.dev/install.sh | sh

The installer checks the download against the published checksums when your system has a SHA-256 tool. Then add the hooks for your agents:

# writes moshterm's own entries; yours are left alonemoshterm-hook install

Agents with managed hooks: Claude Code, Codex, OpenCode, Cursor, Grok Build, Kimi Code, Hermes, Pi and OMP. moshterm-hook uninstall removes only what install wrote.

Pairing

There is nothing to copy. The first time the phone connects over SSH it asks the companion for its token through that same session, and from then on talks to it through the SSH connection. To add a computer from a QR code instead of typing its address, run moshterm-hook pair --qr and scan it with the app.

Where it lives

  • It runs as your user and listens only on 127.0.0.1. On a computer with several accounts, the phone checks it is talking to your companion, not someone else's, before it sends anything.
  • Its state is in ~/.moshterm/, readable only by you.
  • It is a single static binary, built for macOS and Linux on ARM and x86.

Mosh and tmux on the host

For roaming sessions the computer needs mosh-server; for sessions that outlive the connection, a multiplexer. Eternal Terminal is optional.

# macOSbrew install mosh tmux
# Debian, Ubuntu, WSLsudo apt install mosh tmux

When something is off

moshterm-hook doctor prints what the running companion sees: its address, the tools it can find, the state of each agent's hooks, and whether it is paired. It works over SSH, so you can run it from the phone.

Still stuck? Support has the address to write to.