Set up AgentBell

One command connects your computer and adds the Claude Code hooks. Other agents take one more line.

Last updated 9 November 2026 · by the AgentBell team at Surge Software

1. Install

You need Node.js 18 or newer. Run this in any terminal:

$npx -y https://agentbell.surgesoftware.co.in/agentbell.tgz setup

It does three things:

It opens your browser to approve a short code. That connects this computer to your account.
It copies the hook to ~/.agentbell/agentbell.mjs.
It adds hooks to ~/.claude/settings.json (a backup is saved next to it) and sends a test event.

Only for one project? Run npx -y https://agentbell.surgesoftware.co.in/agentbell.tgz install --project inside it. The hooks then go to .claude/settings.local.json.

2. Turn on phone alerts

Open AgentBell on your phone and sign in.
On iPhone, tap Share → Add to Home Screen, then open AgentBell from the home screen. Apple allows web push only for home-screen apps.
Go to Settings → Turn on alerts on this device, then tap Send test.

Claude Code

The hooks report these events:

Claude Code event	AgentBell shows
SessionStart, UserPromptSubmit, PreToolUse	Working
Notification (permission or question)	Needs you, and your phone buzzes
Stop	Finished, with cost, tokens and changed files
StopFailure, PostToolUseFailure	Failed, or a failure on the timeline
SessionEnd	Closed

Approve from your phone (Pro, Team, trial)

Turn it on in Settings → Approve from phone.
Then run npx -y https://agentbell.surgesoftware.co.in/agentbell.tgz install --approvals. This adds a PermissionRequest hook.
When Claude asks to use a tool, your phone shows Allow and Deny.
If you don’t answer within 90 seconds, Claude shows its usual prompt in the terminal.

OpenAI Codex CLI

Add this line to ~/.codex/config.toml (use your home folder path):

notify = ["node", "/Users/you/.agentbell/agentbell.mjs", "codex"]

Codex reports when each turn finishes. AgentBell shows it as Finished and alerts you.

Cursor

Run npx -y https://agentbell.surgesoftware.co.in/agentbell.tgz install-cursor. It adds sessionStart, beforeSubmitPrompt, stop and sessionEnd hooks to ~/.cursor/hooks.json.

Any other agent or long command

agentbell run --name "nightly e2e" -- npm run e2e

You get Working while it runs, then Finished or Failed with the exit code and run time.

Private mode

agentbell private on sends only the status, project folder name, branch, and token and cost totals. No task line, no file names, no tool details. See Security for every field.

All commands

`setup [--approvals]`	Connect, add hooks, send a test
`login [--server URL]`	Connect this computer only
`install [--project] [--approvals]`	Add Claude Code hooks
`uninstall [--project]`	Remove AgentBell hooks. Your other hooks stay.
`install-cursor`	Add Cursor hooks
`run [--name X] -- cmd`	Wrap any command
`status`, `test`	Check the connection, send a test push
`private on\|off`	Private mode

Will it ever break my agent?

No. Each event has a 2-second limit. While you are offline, events wait in ~/.agentbell/queue.jsonl and are sent with the next event. The hook always exits cleanly. The only hook that waits is the opt-in approval hook, and it waits at most 90 seconds before handing back to the terminal.