Set up Grenade with your terminal open.
This page follows what your terminal shows, line by line. Keep them side by side. You need a Mac with Homebrew, or Linux with Node 22, and Claude Code or Codex.
1 · Install the CLI
On a Mac, Homebrew puts grenade on your PATH and brings Node and tmux with it. That is all Grenade needs.
brew install holdgrenade/tap/grenade
Without Homebrew: with Node 22 or newer, npm install -g @holdgrenade/cli installs the same package. tmux 3.2 or newer has to come from somewhere; grenade setup tells you when it is missing.
On Linux, the installer puts grenade in ~/.local/bin. It needs Node 22 or newer, and no sudo: it downloads the release Homebrew installs, checks its sha256 and unpacks it into ~/.local/share/grenade.
curl -fsSL https://www.holdgrenade.com/install.sh | sh
Which Linux: one with systemd. It is tested on Arch Linux, which Omarchy is built on (x86_64). Read the script before you run it. Running it again updates, and Grenade keeps itself up to date after that. What differs on Linux is in the guide.
2 · Answer setup
Run grenade setup. It asks before it changes anything and ends on a QR code.
- What Grenade needs
Setup checks for Node and tmux, and offers to install what is missing. It changes no agent's settings: Grenade starts Claude Code and Codex with the hooks that tell the phone when they work and wait.
- Start at login
The daemon starts when you log in and comes back if it stops.
- Relay
Reach your computer from any network. Phone and computer are end-to-end encrypted: the relay never sees a screen. Say no to stay on the Wi‑Fi.
- The Mac app
A window onto every session, next to your terminal. Setup downloads it, checks it against its published checksum and Apple's notarization, puts it in Applications and opens it. On Linux there is no such step.
- Pair your phone
The QR code works once, for 2 minutes. Leave it up and get the app below.
On Linux setup reads the same, with “this computer” for “this Mac” and four steps, since there is no Mac app to offer. It starts grenaded as a systemd user service, and when a firewall (ufw) is on it names the one command that lets a phone on your Wi‑Fi in: sudo ufw allow 7788/tcp. Through the relay the phone needs no rule.
3 · Pair a phone
Get the app, tap Scan QR code and point it at the terminal. With the relay on, the phone does not have to be on the same Wi‑Fi.
brew install --cask holdgrenade/tap/grenade-app
The Mac app needs no pairing: it is a window onto every session on this Mac, next to your terminal, and needs macOS 26 or later. Setup offered it in step 4; from the terminal it is also one Homebrew command, the same notarized download checked by Homebrew. Or open the download: drag Grenade to Applications, or just open it and it offers to move itself there. On Linux there is no desktop app: the phone shows every session, and grenade open attaches any terminal. The phone app calls a Linux computer your “computer”; before version 1.0.38 it says “Mac”.
4 · Start your first agent
Pick an agent with --agent.
grenade new api --cwd ~/code/shop --agent claude
grenade new web --cwd ~/code/shop --agent codex
grenade new tests --cwd ~/code/shop --agent shell
Watch them in the Mac app or on your phone. On a Mac, want each one in iTerm2 or Terminal too? Run grenade terminal iterm or grenade terminal terminal (more in the guide).
Command reference
Push notifications tell the phone when an agent needs you or has finished, even with the app closed. Your computer seals each one so only your phone can read it; the relay passes it to Apple and learns the device token and the time, never the session or the text. On a Mac, a notification waits while you are at it.
| Command | What it does |
|---|---|
| Sessions | |
grenade ls | Every session and its status |
grenade new <name> --cwd <folder> | Start an agent in a new tmux session; --agent claude, codex or shell; --alone keeps it out of the folder's group |
grenade open <name> | Attach this terminal to a session (Ctrl-b d to detach) |
grenade terminal iterm | On a Mac: open every session in iTerm2 too (terminal for Terminal.app, none to stop) |
grenade kill <name> | End a session |
| Phones and the daemon | |
grenade pair | Pair another phone |
grenade devices | The phones paired with this computer |
grenade unpair <phone> | End a phone's pairing; its token stops working at once |
grenade status | Is the daemon running? |
grenade service status | Is the start-at-login service installed and running? |
grenade update | Install the newest version now; grenaded also does it by itself |
| Push notifications | |
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 | Push also with remote access off, through the main relay |
grenade push on --at-mac 0 | On a Mac: never wait for you to leave it |
grenade push off | No push; the phone notifies only while the app runs |
grenade push auto | The default: on while remote access is on |
| Talk | |
grenade voice | The providers for Talk, and which hold your API key |
grenade voice key openai | Keep your OpenAI key for Talk on this computer; gemini the same way |
grenade voice forget openai | Forget it |
| Setup, one part at a time | |
grenade install-hooks | Also report a claude you start by hand in a Grenade shell |
grenade install-hooks --remove | Take those hooks out again |
grenade app install | On a Mac: download the Mac app, check it and put it in Applications |
grenade service install | Start grenaded at login and keep it running |
grenade service remove | Stop starting it at login |
grenade relay on | Turn on the relay |
grenade relay off | Turn it off; the phone reaches this computer on the same Wi‑Fi only |
grenade pair | Show the QR code and wait for the phone |