@trygocode/notify

Get a push notification on your phone the moment your AI coding agent finishes.
Cursor · Claude Code · OpenCode · Ralph Wiggum / Autopilot script loops — installed with one command.

npx @trygocode/notify@latest setup

Free. @trygocode/notify and the GoCode phone app that receives the pushes are both free to use.

You need the GoCode app. Notifications are delivered to your phone through the free GoCode app — it's the pairing target and the thing your phone buzzes with. Install it, pair once (a 6-digit code), done. Without it there's nowhere for the pushes to land.

---

Why?

You kick off a long agent run, then walk away to make coffee, take a call, or context-switch to something else. Now you're stuck in the loop of checking back every 30 seconds to see if it's done — or worse, it finished 20 minutes ago and you didn't notice.

@trygocode/notify pings your phone the instant your agent finishes a turn, goes idle waiting for you, errors out, or an overnight loop completes/halts. Walk away. Your phone tells you when it needs you.

• 🆓 Free. The package and the GoCode phone app are free. No card, no trial.
• ⚡ One command. npx @trygocode/notify@latest setup — no server to host, no config files to hand-edit.
• 🔒 Push-only & private. The paired key can only send notifications to your phone. It can't read your chats, code, or settings. Revoke it any time.
• 🧩 Auto-detects your tools. Wires up Cursor, Claude Code, and OpenCode in one go — never clobbering your existing hooks/MCP config.
• 🪶 Never blocks your agent. Every send is fire-and-forget with a hard timeout + an offline queue. A slow push can't slow your work.

Works with

Tool	How it hooks in
Cursor	stop hook
Claude Code	Stop + Notification + SubagentStop hooks
OpenCode	runtime hook
Ralph Wiggum / Autopilot script loops	opt-in completion/halt snippet

Requires the free GoCode phone app. It's the one-time pairing target and where every push lands. Install GoCode, pair once, done — both the app and this package are free.

Contents

• Install — two equally-supported paths
• Pairing — step by step
• The three triggers
• Loop opt-in snippet (trigger C)
• GoCode platform settings (auto-push, pull-before-push & more)
• Troubleshooting
• Develop
• Layout

Install — two equally-supported paths

Both paths converge on the same installer (gocode-notify setup): it pairs this machine, auto-detects your agent runtimes, and merges the hooks + MCP server + anti-double-ping rule into each one's config (never clobbering your existing settings; safe to re-run).

Path 1 — paste a one-liner into your terminal

npx @trygocode/notify@latest setup

This runs the interactive installer: it prompts for the 6-digit pairing code (from the GoCode app → "Connect a coding agent"), then detects and configures Claude Code / Cursor / OpenCode. Re-run any time — it's idempotent; pass --force to re-pair.

First time? You'll need the free GoCode app on your phone to receive the pushes and to generate the 6-digit pairing code (Settings → "Connect a coding agent").

Path 2 — paste a prompt into your AI agent and let it install

Hand this to Cursor / Claude Code and the agent does the install for you. The --agent-driven flag suppresses interactive prompts and emits one JSON line per step so the agent can verify each one:

Install GoCode phone notifications for this machine. Run:
  npx @trygocode/notify@latest setup --agent-driven --pair-code <CODE>
Then confirm the hooks and MCP server were written, and run
  npx @trygocode/notify@latest test
to send a test push to my phone. Report whether the test push arrived.

Replace <CODE> with the 6-digit code from the GoCode app. --agent-driven is fully idempotent and machine-readable; it never spawns a prompt.

Pairing — step by step

A dev machine running agent hooks has no GoCode login (no JWT), so it can't use GitHub OAuth. Instead you pair it once with a short-lived 6-digit code, which the CLI exchanges for a scoped, push-only API key stored locally. The key can only send pushes to your phone — it can't read chats, settings, or trigger any agent action, and you can revoke it from the app at any time.

1. In the GoCode app, open Settings → "Connect a coding agent". The app shows a large 6-digit code (valid 10 minutes), a copyable npx @trygocode/notify login --code 123456 line, and a 10:00 countdown. Tap "Generate new code" if it expires.

2. On the machine, either run the full installer (npx @trygocode/notify@latest setup, which pairs and writes your agent configs) or just pair on its own:

   # Interactive — prompts for the code:
   npx @trygocode/notify@latest login
   
   # Or pass it directly (and optionally label this machine):
   npx @trygocode/notify@latest login --code 123456 --label "MacBook Pro — Cursor"
   

3. The CLI calls the server's pair/claim endpoint, receives the API key once, and writes it to ~/.gocode/credentials (chmod 600). The app flips to a "connected ✓" success state showing the machine's label.

4. Verify the round-trip with a real push to your phone:

   npx @trygocode/notify@latest test
   

   A "GoCode test" notification should arrive on your paired device. If it doesn't, see Troubleshooting.

Re-pairing. Both login and setup are idempotent — re-running them won't clobber an existing pairing. To deliberately replace the stored key (new machine owner, rotated key), pass --force to setup (or just run login again with a fresh code). Revoke an old machine from the app's "Connected agents" screen.

Server selection. Pairing and every send resolve the server URL in this precedence order: the --server flag → the GOCODE_SERVER env var → the value saved in ~/.gocode/credentials → the built-in default (https://oh.jeltechsolutions.com). You only need --server for a self-hosted or staging GoCode server.

The three triggers

Trigger	Mechanism	Fires when
(A) Runtime hook	Cursor stop / Claude Code Stop+Notification+SubagentStop	Agent finishes a turn, goes idle, or errors — automatic, the killer feature
(B) MCP tool	gocode_notify tool the agent calls	You explicitly ask "ping me when X is done" mid-task
(C) Loop shell hook	one line in your loop's completion/halt path	A Ralph Wiggum / Autopilot script loop reaches completed / halted

The installed rule/skill tells the agent not to call the MCP tool for done/idle/error pings — those are owned by the deterministic hook (A), so you never get double-pinged.

Loop opt-in snippet (trigger C)

For power users running an autonomous loop they control — a Ralph Wiggum-style "keep prompting until done" loop, an Autopilot script, a while :; do … done one-liner, or any custom driver — drop these two lines into the loop's completion/halt path:

# At loop completion:
npx -y @trygocode/notify send --kind loop_completed --source ralph --project "$(basename "$PWD")" || true
# At loop halt (paused_max_failures / awaiting_human):
npx -y @trygocode/notify send --kind loop_halted --source ralph --project "$(basename "$PWD")" \
  --title "Ralph halted — needs you" || true

The ready-to-copy version with comments lives at snippets/ralph-homer.sh.

This is opt-in and never auto-injected — the installer does not edit your loop scripts. Both lines are fire-and-forget (|| true + the CLI's 5s self-timeout), so a failed or slow push can never block or fail your loop.

GoCode platform settings

This package is the notifier. The richer automation lives in the free GoCode phone app (Settings → per-project + global), which uses these notifications as its signalling layer. Once paired, the app gives you:

Setting	What it does
Notification preferences	Choose which events ping your phone — done / idle / error, loop completed, loop halted, agent questions, merge-ready — globally or per project.
Auto-push to git	Opt-in: after a turn, the agent commits + pushes to a chosen branch so your work is never stranded on one machine and you can pick up anywhere. Off by default.
Pull-before-push (safe)	When auto-push is on, a git pull --rebase --autostash runs first so remote changes merge cleanly. On a real conflict it aborts safely (nothing lost) and pings your phone.
AI-Solve conflicts	If a push hits a conflict, the notification deep-links into the chat with two actions: Acknowledge or AI-Solve — your agent diagnoses local vs remote and resolves it with no code loss, asking you only when it's unsure.
Review & merge / Create PR	When an Autopilot loop finishes on its own branch, you get a merge-ready ping; choose Merge & push (solo repos) or Create PR (teams), with a remembered default branch.
Default LLM & loop model	Per-project defaults for the agent model and the Autopilot loop model.

These toggles are configured in the GoCode app, not in this npm package — the package just delivers the pings that drive them. All of it is free.

Troubleshooting

Start here: gocode-notify status prints a one-screen report — whether credentials are present (and the bound user/label), whether the server is reachable, which agent runtimes were detected, and whether each one's config has been written. Most issues below are diagnosable from that output.

Symptom	Likely cause & fix
test / send prints "not paired"	No ~/.gocode/credentials. Run gocode-notify login and pair from the app (see Pairing).
Pairing fails ("invalid or expired code")	Codes expire after 10 min and are single-use. Tap "Generate new code" in the app and re-run login with the fresh code.
status shows Server: not reachable	Network/DNS/firewall, or a wrong server URL. Confirm you can reach https://oh.jeltechsolutions.com; check the --server flag / GOCODE_SERVER env / the server field in ~/.gocode/credentials.
No push arrives even though test exits 0	The send is fire-and-forget and exits 0 even on failure — check ~/.gocode/notify.log for the real error. Also confirm push permissions are granted in the GoCode app and the device token is registered (re-open the app once after signing in).
Double pings (two notifications per event)	The agent is calling the gocode_notify MCP tool and the runtime hook is firing. Re-run setup so the anti-double-ping rule/skill is installed; it tells the agent not to notify for automatic done/idle/error events.
Hook doesn't fire in Cursor / Claude Code	Re-run setup and check status shows "config written" for that runtime. Restart the agent app so it reloads ~/.cursor/hooks.json / ~/.claude/settings.json. The hooks are merged, never clobbered — your existing hooks are preserved.
Pushes queue up while offline then arrive later	Expected. Sends made while the server is unreachable are enqueued to ~/.gocode/outbox/ (size-capped, drop-oldest) and flushed best-effort on the next send. A missed "done" ping is acceptable; a blocked agent is not.
npx @trygocode/notify can't find the package	Make sure you're online and using the scoped name exactly: npx @trygocode/notify@latest setup. Clear a stale npx cache with npx clear-npx-cache (or rm -rf ~/.npm/_npx) and retry.
Want it gone	gocode-notify uninstall removes exactly the hook/MCP/rule entries this tool added (nothing else). Delete ~/.gocode/ to also drop the stored credentials, and revoke the key from the app's "Connected agents" screen.

Logs & files. Failures are appended to ~/.gocode/notify.log (size-capped, rotated to notify.log.1). Credentials live in ~/.gocode/credentials (chmod 600); non-secret prefs in ~/.gocode/config.json; the offline queue in ~/.gocode/outbox/.

Found a bug or have a feature idea? Please open an issue — issues are welcome and usually get a reply within a day or two.

Develop

git clone https://github.com/joseph-lewis/gocode-notify.git
cd gocode-notify
npm install
npm run build      # compile TypeScript -> dist/
npm test           # builds, then runs node --test on dist/test/
npm run typecheck  # type-check only, no emit

Zero runtime dependencies beyond the MCP SDK (Node built-in fetch/fs/ readline for everything else). Tests use Node's built-in test runner (node:test).

Layout

Path	Purpose
src/cli.ts	gocode-notify bin entrypoint + command dispatcher
src/setup.ts	Installer orchestration (pair → detect → write configs)
src/claude.ts / src/cursor.ts	Per-client config writers (hooks + MCP + rule/skill)
src/send.ts / src/login.ts / src/mcp.ts	Core send, pairing, and MCP server
snippets/ralph-homer.sh	Opt-in loop completion/halt snippet (trigger C)
test/	node:test smoke + unit tests