Quickstart
Connect Claude Code, Codex, Gemini CLI, Cursor, Hermes or another AI agent to your phone with one command. Then approve risky actions from anywhere.
This quickstart connects your AI agent to your phone. Run one command on the computer where your agent works, then open the QR link on your phone. You sign in or create an account during pairing, and setup saves your key automatically. Supported hooks apply your approval policy, including its wait and timeout behavior. It works with Claude Code, Codex, Gemini CLI, Cursor, VS Code, OpenCode, Hermes, fx and the other supported agents.
npx pushary@latest setupOn a Mac? The Mac app, Pushary Isle, finds your agents and sets them up for you. No terminal needed.
What you need
- Your AI agent, installed on the computer where it runs.
- Node.js for CLI setup: 20.17 or newer (22.13+, 23.5+ and 24+ also work; 21 does not). Check with
node -v. Get Node.js. Native Mac app setup does not need Node/npm. - Your phone. Install the Pushary app from the App Store or Google Play, before or during pairing.
- A Pushary account and paid plan. During pairing, the phone app shows the store's local price and any eligible trial. Review its price, trial eligibility and payment method before confirming. Eligible web signups offer a 3-day trial with a card required, then $9.99 a month for the Agent plan; these web terms do not determine native store offers. Existing subscribers sign in to the same account.
Already set up?
Keep the installation that already owns your agent's hooks. For Mac app setup, check the intended account, subscription and agent connection in the app, use its connection/repair controls, and send a harmless test question through your current agent. Do not install Node/npm to inspect native setup.
For CLI-owned setup with Node/npm available, run npx pushary@latest status --json to check the selected account and answering devices before running setup again. Use Troubleshooting to repair it. Changing hook ownership is an explicit choice described in the CLI reference.
If your AI agent is doing setup
Give it this page and the Pushary agent skill. It should first check the computer and preserve any existing setup owner. For fresh CLI setup, it runs setup, shows you the exact phone link and fingerprint, and keeps the process running while you connect. You complete sign-in, subscription checkout where required, notification permission, and connection approval on your phone.
Setup works with piped output and automatically selects detected agents without a terminal checkbox. To connect only one, your agent can run npx pushary@latest setup --agents codex, for example. CI without a key cannot pair. Do not use --skip-phone when the goal is phone approvals, or claim that tools are available before the agent restarts and loads them.
Set it up
Run setup on your computer
Open a terminal on the computer where your agent runs and paste:
npx pushary@latest setupOn Windows PowerShell, use npx.cmd pushary@latest setup instead.
The terminal shows a QR code, a phone link, and a fingerprint under Connect your phone. Keep setup running while you complete the phone steps; the pairing code lasts about 15 minutes.
Open the link on your phone and sign in
Scan the QR with your phone's camera or open the printed link on your phone. Install the Pushary app if needed, then sign in or create an account. Activate a plan if required, reviewing the displayed price and any trial offer first; existing subscribers use the same account. After installing the app, return to the original phone link and tap Open Pushary to finish connecting. If the app restarts during sign-in or payment, reopen that link or scan again. Setup keeps waiting while you do this; if the code expires, run setup again for a fresh one. You can also scan from inside the app.
Approve the connection
The app asks Connect this computer? Check that the code on your phone matches the code in the terminal, then tap Approve. Allow notifications when the app asks.
The terminal says App connected. Your API key is now created and saved on this computer. There is nothing to copy or paste.
Pick your agents
At an interactive terminal, setup asks Which agents do you use? The agents it found on your computer are already ticked. Press space to tick or untick one, then Enter. When an AI agent runs setup with piped output, detected agents are selected automatically; --agents selects the ones to configure.
Setup then writes each agent's config: the Pushary MCP server, and approval hooks for agents that support them. It may ask two yes or no questions, and both default to No:
- Add a Pushary section to
CLAUDE.mdorAGENTS.mdin this folder, so agents here know to ask through Pushary. - Start
claudethrough Pushary, so your phone can reach idle Claude Code sessions.
Answer the test question
Setup sends a test notification, then a test question. Your phone buzzes. Answer the question on your phone.
Read the result to see which surface answered. A returned test answer proves the question-and-answer path; native hook enforcement is checked in the next step. A skipped or unanswered test does not prove phone approvals work.
Try a real approval
Restart your agent so it loads the new MCP tools, instructions and hooks. Follow its setup guide, including hook trust where required.
Through that agent, try a harmless action that your policy requires approval for. For Claude Code, follow its real approval check with a new scratch file. For Codex, its setup guide uses curl -I https://example.com. Check that the action waits for your answer, then resumes when you approve. If it runs without asking, check the integration and policy before reporting enforcement as verified. An MCP-only connection can ask questions but does not intercept every tool call.
If you want to test phone delivery while at your desk, select Always in the app's Questions & approvals settings, then restore your preferred mode after testing. Your agent should leave this setting to you. Confirm the phone receives the request and the answer returns to the same task.
Where does the approval show up?
New accounts start in the Always approval mode. In this mode, approvals go to your phone wherever you are, and the agent waits for your answer. If you do not answer within 60 seconds, the agent asks in its own prompt instead. To keep your phone quiet while you are at the agent's computer, open the Pushary app, tap Questions & approvals at the top of your inbox, and pick When away. See Policies for all four modes.
Check that everything works
For Mac app setup, use its connection tests and send a harmless question through your current agent. The CLI cannot verify a roundtrip when the app holds the key and the CLI has no credential.
For CLI-owned setup with Node/npm available, run:
npx pushary@latest doctorIt checks your key and plan, how each agent is wired, and the connection to Pushary. At an interactive terminal it also sends a test notification; piped runs skip that push by default. Add --roundtrip to explicitly send a test notification and question and wait for your answer. This synthetic test does not run a tool through your agent's hooks, and an answer from your Mac or browser does not prove phone delivery. Check the intended surface and the real approval step above before calling setup verified.
If something goes wrong
- No phone app, or a phone that cannot scan? Press Ctrl-C, then run
npx pushary@latest setup --connect browser. You sign in through a browser tab, and you can get push notifications in your phone's browser instead of the app. - "Your Pushary workspace has no active subscription": activate a plan in the app or at pushary.com, then run setup again.
- The QR code stopped working: it lasts 15 minutes. Run setup again for a new one.
- Setup already ran on this computer and you want to add the app now: run
npx pushary@latest setup --connect app. A plainsetupreuses your saved key and does not show a QR code.
More fixes are in Troubleshooting.
Setup options
| Option | What it does |
|---|---|
--agents claude_code,codex | Connect these agents without asking. auto picks every agent found; none saves the key only. |
--yes | Accept the defaults without prompts. |
--key pk_xxx.xxx | Use a key you already have. Skips the QR code and sign-in. |
--key-stdin | Read the key from standard input, so it never appears in your shell history or CI logs. |
--connect app | Pair the phone app, even if this computer already has a key. This creates a new key. |
--connect browser | Sign in through a browser tab instead of the phone app. |
--skip-phone | Skip the phone step, for CI or scripts. |
The CLI reference lists every command and flag.
Next steps
Set up your agent
What Pushary changes and enforces for Claude Code, Codex, Gemini CLI, Cursor, Hermes and more.
Choose what needs your approval
Policies decide which actions run on their own and which ask your phone first.