How Grenade works

grenade new starts one on your Mac or Linux computer: it shows on the phone and in the Mac app. Closing a terminal window doesn't stop it; grenade kill does.

grenade new api --cwd ~/code/shop --agent claude   # Claude Code in ~/code/shop
grenade ls                                         # every session and its status
grenade open api                                   # attach here; Ctrl-b d detaches
grenade kill api                                   # end it

grenade new tests --cwd ~/code/shop --agent shell   # same folder: joins api's group
grenade new docs --cwd ~/code/shop --alone          # same folder, on its own
grenade new web --cwd ~/code/web --with api         # another folder, api's group
grenade group tests api                             # move tests next to api
grenade ungroup tests                               # on its own again

--alone keeps a session out. --with joins any group. On the phone, drag to move.

Claude Code and Codex report through hooks; a shell is read from the screen. Each session also gets a one-line summary, written on your computer by claude -p.

The Mac app and your phone show every session, so Grenade opens no terminal window by itself. To have each session in a terminal too, pick one: in iTerm2 a group is one tab, its sessions side by side. It applies at once, to sessions already running too. When macOS asks whether node may control iTerm2 or Terminal, allow it. Every window is tmux attach, so grenade open joins from any terminal.

grenade terminal iterm      # every session in iTerm2, a tab per group
grenade terminal terminal   # every session in a Terminal window of its own
grenade terminal none       # back to no windows, the default
grenade terminal            # what is set

~/.grenade/

Paired phones, keys, relay and push settings, your API keys for Talk, attachments, the log.

~/.claude/settings.json

Untouched, unless you run grenade install-hooks.

~/Library/LaunchAgents/com.adamchew.grenade.daemon.plist

On a Mac: the login agent, with your terminal's PATH.

~/.config/systemd/user/grenade.service

On Linux: the login service, with your terminal's PATH.

~/.local/share/grenade/

On Linux: Grenade itself, as the installer unpacked it.

tmux

Sessions named gr-<name>. They outlive the daemon.

grenade status                     # is grenaded running?
grenade service status             # does it start at login?
grenade service remove             # stop it; sessions keep running
tail -f ~/.grenade/daemon.log      # the log
GRENADE_LOG=debug grenade daemon   # run it here, with every detail

GrenadeFileEditView

api-refactorOpen

PermissionRun this command?

5m

Run the rooms migration

$ npm run migrate -- --only 0042_rooms

Bash

DenyAllow once

websiteRegenerated the logo PNGs.

Open

ios-app and grenade working

• The ring. While sessions run, Grenade's Dock icon has a ring round it in the status colors, each its share of your sessions: amber needs you, green finished, blue working, a dashed blue in the background. It counts every computer the app is added to, and goes away when nothing runs.
• The Dock menu. Right-click the icon: the sessions that need an answer, then the finished ones, then the working ones, under each computer's name. Pick one and the window opens on it. New Session, Command Center and pairing are there too.
• The session shelf. A strip of status dots that floats over every app, on the screen's right edge. Click it, or press ⌃⌥Space from any app, and it opens beside the strip: a question or a permission is answered right there, a finished session has Open. Hovering only says what is there. Esc or a click elsewhere closes it.
• Where it sits. Grenade › Settings… › Session Shelf: the screen's edge (left or right, top, middle or bottom), above the Dock, or under the menu bar, or off. The Dock menu's Session Shelf changes it too.
• Since Mac app 1.0.126. The shortcut changes in Settings › Keyboard like every other.

To change one, open Grenade › Settings… (⌘,) › Keyboard, click its keys and press new ones. Esc cancels, Delete leaves it with none. Your keys are kept by the app on the Mac you type on, never by the daemon, so they stay the same whichever computer the app shows. ⌘/ shows them over the window. 7 more actions, such as Pair a Phone or Computer and Open Canvas, start with no key until you give them one. Since Mac app 1.0.123.

curl -fsSL https://www.holdgrenade.com/install.sh | sh   # install, or update
grenade setup                                            # start at login, relay, QR code
sudo ufw allow 7788/tcp                                  # with a firewall, for the same Wi‑Fi
systemctl --user status grenade                          # the service
loginctl enable-linger $USER                             # keep it running after you log out

• Which Linux. One with systemd, Node 22 or newer and tmux 3.2 or newer. Tested on Arch Linux, which Omarchy is built on (x86_64).
• Installing. No sudo and no npm: the installer downloads the release Homebrew installs, checks its sha256, unpacks it into ~/.local/share/grenade and links ~/.local/bin/grenade. Grenade then keeps itself up to date the same way; grenade update does it now.
• Starting at login. A systemd user service. It runs while you are logged in; on a machine nobody sits at, loginctl enable-linger keeps it running.
• A firewall. ufw (Omarchy, Ubuntu) refuses a phone on your Wi‑Fi until you allow port 7788. grenade setup tells you when it is on. Through the relay the phone gets in without a rule.
• Watching sessions. On the phone, or in any terminal with grenade open. The Mac app, and opening sessions in iTerm2 or Terminal, are for a Mac.
• Your tmux. Grenade uses your tmux and your tmux.conf, Omarchy's included. Stopping or restarting the service leaves every session running.
• What the apps call it. Your “computer”, where they say “Mac” for a Mac. The iPhone app before 1.0.38 says “Mac” for both.
• Not there yet. On a Mac a push notification waits while you are at the keyboard. On Linux it is sent at once.

• Claude Code's permissions, questions and plans arrive as cards. The first answer wins, phone or computer.
• Codex approvals: tap the key row or type. Its startup dialogs come as cards.
• A photo lands in ~/.grenade/attachments/, and its path goes to the agent.
• With the relay on, a push tells you when an agent needs you or is done. Apple and the relay see only a token and the time.

The code works once, for two minutes. With the relay on, pair from anywhere.

grenade pair             # show the QR code
grenade devices          # the paired phones
grenade unpair <phone>   # end a pairing now

Ask what your agents are doing, have one's reply read to you, tell it what to send. The model runs at OpenAI or at Google (Gemini), under your own API key. Nothing is on until you give your computer a key.

grenade voice key openai   # paste your OpenAI key when asked; it is checked, then kept
grenade voice key gemini   # the same, for Google's Gemini
grenade voice              # the providers, and which hold a key

• Get a key. From your own account with the provider: platform.openai.com for OpenAI, aistudio.google.com for Gemini. The provider bills what you use; the app shows an estimate as you go.
• Give it to your computer. Run the command and paste the key when asked. It is not shown, and Grenade checks it with the provider before keeping it. Or paste it in the app, in Talk's settings: the app hands it to your computer.
• Start. In the Mac app, click the Talk button in the toolbar. On the iPhone, open the Talk tab and tap the circle. Tap again to pause.
• What it can do. Tell you about your sessions, read you what an agent said, start a session, and send a session a prompt when you ask. It cannot answer a permission, a question or a plan: that stays a card for you.
• Highlights. When a session finishes a turn, its row in the thread (Command Center in the apps) shows what the turn made: the boards it saved on the canvas, the screenshots it took or you sent it, and its push, with your prompt and its own sentences. On a phone, a tap opens the turn as one page you scroll: your prompt, its words, the pictures whole and the push, in the order they happened, with Share at the bottom right; a tap on the commits shows only the changes. On the Mac, a picture opens full-screen, and from three pictures they play as a reel, the turn's words between them. Your computer gathers them from the files it already has and asks no model; they reach a phone only inside the encrypted channel, never in a notification. Hold a picture to remove it from highlights on every device: your computer deletes its copy. Grenade 1.0.81 on the computer and the Mac app 1.0.179, or later.
• What the provider gets. Your voice while a conversation is live, your sessions' titles, folders, statuses and summaries, and what an agent said when it reads a session for you. It goes straight from the app to the provider, never through a relay.
• Which version. The Mac app 1.0.78 or the iPhone app 1.0.53, or later, with Grenade 1.0.43 or later on the computer.

The mic turns what you say into text with the device's own speech recognition, and puts it in the session's field for you to fix and send.

• Hold or tap. Hold the mic and speak until you let go, or tap to start and tap again to stop. On the Mac app each pane's field has the same mic.
• Fix, then send. The words land in the field as you talk. Nothing goes to the agent until you send it.
• Where the audio goes. To Apple's speech recognition (the phone's own on Android), on the device where it supports that. Never to your computer, a relay or us.
• Nothing to set up. No key and no command. The first time, the app asks for the microphone and speech recognition.

• On your computer only. In ~/.grenade/voice-keys.json, readable by you alone. A key pasted in an app travels to your computer inside the encrypted connection, and the app does not keep it.
• The app gets a pass, not the key. Each time it connects to a provider, the app asks your computer, and your computer has the provider make a pass that lasts about a minute.
• Never shown again. grenade voice and the apps show a kept key masked, like sk-…a1b2. Nothing sends it back whole.
• Forgetting one. grenade voice forget <provider>, or Forget in the app, removes it at once. To make the key itself worthless, revoke it at the provider.
• Several computers. A key lives on the computer you gave it to. A phone paired with several uses whichever connected one holds it.
• A key from before. One that an earlier version of an app kept is moved to your computer the first time that app connects, and deleted from the app.

What that means for someone holding your phone is on the security page.