Install

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.

Mac
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.

Linux
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.

Mac
grenade setup
1What Grenade needs
ok: macOS, Node and tmux are in place
2Start at login
Start grenaded at login and keep it running? [Y/n] y
3Reach this Mac from anywhere
Turn on the Grenade relay? [Y/n] y
4The Mac app
Install the Grenade Mac app in Applications? [Y/n] y
5Pair your phone
OPTION 1 · SCAN THE QR CODE
In the Grenade app, tap "Scan QR code".
OPTION 2 · TYPE THE CODE
Pick this Mac in the app. Same Wi‑Fi only.
Waiting for the phone… (Ctrl-C to stop)
  1. 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.

  2. Start at login

    The daemon starts when you log in and comes back if it stops.

  3. 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.

  4. 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.

  5. 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.

Mac app, from Homebrew
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.

Mac or Linux
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.

CommandWhat it does
Sessions
grenade lsEvery 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 itermOn 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 pairPair another phone
grenade devicesThe phones paired with this computer
grenade unpair <phone>End a phone's pairing; its token stops working at once
grenade statusIs the daemon running?
grenade service statusIs the start-at-login service installed and running?
grenade updateInstall the newest version now; grenaded also does it by itself
Push notifications
grenade push statusOn or off, through which relay, which phones asked for it
grenade push testSend every registered phone a test notification
grenade push onPush also with remote access off, through the main relay
grenade push on --at-mac 0On a Mac: never wait for you to leave it
grenade push offNo push; the phone notifies only while the app runs
grenade push autoThe default: on while remote access is on
Talk
grenade voiceThe providers for Talk, and which hold your API key
grenade voice key openaiKeep your OpenAI key for Talk on this computer; gemini the same way
grenade voice forget openaiForget it
Setup, one part at a time
grenade install-hooksAlso report a claude you start by hand in a Grenade shell
grenade install-hooks --removeTake those hooks out again
grenade app installOn a Mac: download the Mac app, check it and put it in Applications
grenade service installStart grenaded at login and keep it running
grenade service removeStop starting it at login
grenade relay onTurn on the relay
grenade relay offTurn it off; the phone reaches this computer on the same Wi‑Fi only
grenade pairShow the QR code and wait for the phone
Host your own relay