Install

On the Mac, two steps.

You need macOS, Homebrew, and Claude Code or Codex. The phone app talks to the daemon these steps set up.

Not released yet. The Homebrew tap, the npm package and the iPhone app are not published. This page shows how Grenade will install when they are.

1
Install Grenade
Homebrew puts grenade on your PATH and brings Node and tmux with it.
Mac
```
$ brew install holdgrenade/tap/grenade
```
2
Set it up and pair your phone
One command does the rest. It asks before it changes anything, skips what is already done, and ends on a QR code. Scan it in the Grenade app and the phone is paired.
Mac
```
$ grenade setup
```

What setup does

Four things, in this order. Each can be taken back with one command.

Claude Code hooks

It shows the hooks it would add to ~/.claude/settings.json, event by event, and adds them only if you say yes. They tell the daemon on this Mac when Claude Code is working and when it waits for you. Your other hooks and settings stay as they are. Say no, and the phone guesses the status from screen changes.

Take it back: grenade install-hooks --remove

Start at login

It installs a launchd agent, so the daemon starts when you log in and comes back if it stops. Your agents run in tmux and keep running either way.

Take it back: grenade service remove

Reach the Mac from anywhere

It offers to turn on the relay. The relay learns this Mac's name and IP addresses and when it is online. It never sees a screen, a prompt or a session name: everything between phone and Mac is end-to-end encrypted. Say no, and the phone reaches the Mac on the same Wi‑Fi only and the Mac talks to no relay. Push notifications follow this answer: with the relay on, the Mac posts each one sealed to that relay, which learns the phone's device token and the time, never the text. grenade push off turns only them off.

Take it back: grenade relay off

Pair the phone

The QR code carries the Mac's key and a one-time secret, so the phone knows it is talking to your Mac and nothing is typed. With the relay on, the phone does not have to be on the same Wi‑Fi. The code works once and runs out in 2 minutes. Beside it is a code you can type instead, on the same Wi‑Fi.

Take it back: grenade unpair <phone>

grenade setup --yes takes the suggested answer to every question. --no-hooks, --no-service, --no-relay and --no-pair leave a part out.

Start an agent

Each session runs in tmux, so closing a window never kills it. Sessions in the same folder form a group and sit side by side in one tab; --alone starts one on its own. With iTerm2 installed, every session also gets its own iTerm tab on the Mac.

Mac

$ grenade new myproject --cwd ~/code/myproject --agent claude
$ grenade new tests --cwd ~/code/myproject --agent shell
$ grenade ls

Every day

Mac

$ grenade open myproject     # attach this terminal (Ctrl-b d to detach)
$ grenade kill myproject
$ grenade pair               # pair another phone
$ grenade devices            # the phones paired with this Mac
$ grenade status
$ grenade service status

Host your own relay

Push notifications

The phone is told when an agent needs an answer or has finished, even while the app is closed. Push follows remote access: with the relay on it is on, with the relay off it is off and the Mac talks to no relay. grenade push on turns it on by itself, through the main relay. The Mac seals each notification so that only your phone can read it, and the relay passes it to Apple. That relay learns the Mac's public IP address, the phone's device token and the time. It never learns the session, the question or the Mac's name.

A notification waits while you are at the Mac (keyboard or mouse used in the last two minutes) and is dropped once you have answered. On the phone, the ⋯ menu chooses what you are told about.

Mac

$ grenade push status        # on or off, through which relay, which phones asked for it
$ grenade push test          # send every registered phone a test notification
$ grenade push on            # also with remote access off, through the main relay
$ grenade push on --at-mac 0 # never wait for you to leave the Mac
$ grenade push off
$ grenade push auto          # the default: on while remote access is on

Step by step instead

Setup runs these for you. Run them yourself if you would rather do one part at a time.

Mac

$ grenade install-hooks
$ grenade service install
$ grenade relay on
$ grenade pair

Without Homebrew

With Node 22 or newer already on the Mac, npm installs the same package. tmux 3.2 or newer has to come from somewhere; grenade setup tells you when it is missing.

Mac

$ brew install tmux
$ npm install -g grenade-remote
$ grenade setup

Or build it from the source:

Mac

$ brew install tmux
$ cd grenade-protocol && npm install && npm run build
$ cd ../grenade-backend && npm install && npm run build && npm link
$ grenade setup