Code Alarm

Your agent is done. Your phone rings.
A real alarm on your phone when Claude Code or Codex finishes, fails or needs you.

Quick start · Use it · How it works · Commands · Protocol

Coding agents now work for an hour or more on their own. Their apps can notify you when they're done, but Do Not Disturb swallows a notification and it only sounds once. Code Alarm rings like an alarm, and only for the work you armed. Start a long task, go make dinner or go to sleep, and come back when the agent actually needs you.

Only armed work rings Sessions you didn't arm stay silent. Old and duplicate alerts never ring.	Knows why it stopped Done, needs you (a question or a permission prompt), failed or stopped.	Loud, or quiet A repeating alarm by default, or one ordinary notification when you arm it with quiet.
Private by design Only the event's kind, the folder's name and the agent leave your computer. No prompts, code or transcripts.	Never slows your agent Hooks return at once and send in the background, so a bad network can't stall a session.	Free and open source The CLI, the hooks and the Claude Code plugin are MIT, all in this repository.

Quick start

You need Node.js 22 or newer on the computer that runs your agent, and an app on your phone to ring: the Code Alarm app or ntfy.

	Code Alarm app	ntfy
Phones	Android	Android and iPhone
Available	In closed testing: join the testers group	Now, free
How it rings	A full-screen alarm over the lock screen, on the alarm volume, with Stop and Snooze	ntfy's highest-priority alert, which keeps alerting once you turn that on
Set up with	npx code-alarm pair and a QR scan	npx code-alarm init and a topic subscription

1. Connect your phone

With the Code Alarm app. Once you're in the test, install it from Google Play, then run this on your computer:

npx code-alarm pair

It shows a QR code. In the app, tap Pair a computer, then Scan QR code, and confirm. No camera? Choose Show a code instead in the app and run npx code-alarm pair <that code>.

With ntfy (Android or iPhone)

Create your private alarm channel:

npx code-alarm init

It prints a long random ntfy topic. Treat it like a password: anyone who knows it can ring your phone. Install ntfy (Google Play, F-Droid, App Store) and subscribe to that topic. In the subscription's settings, turn on keep alerting for the highest priority and the Do Not Disturb override.

Then ring it once to check:

npx code-alarm test

2. Connect your agent

Claude Code: add the plugin.

claude plugin marketplace add Draganoider/code-alarm

claude plugin install code-alarm@code-alarm

Codex: add user-level hooks and a skill, then open Codex and trust the new hooks.

npx code-alarm install codex

Use it

Before a long task, arm it:

Where	How
Claude Code	/code-alarm:alarm, then give it the task, or just say "wake me when it's done"
Codex	"Use the code-alarm skill and …", or "wake me when it's done"
Any terminal	code-alarm arm in the project folder, or code-alarm nap 2h to arm every session for two hours

The agent ends its work with done, needs-you or failed, and your phone rings with that reason. If it forgets, the alarm still rings when it stops, labelled stopped.

Prefer a plain notification? Say quiet: /code-alarm:alarm quiet …, "quietly notify me when done", or code-alarm arm --notify. You get one normal notification with sound and vibration, following your phone's sound settings, instead of the repeating alarm.

How it works

• Arming decides. Hooks fire for every session, but code-alarm only sends for work you armed. Arming a folder lasts until its first end-of-task alert; nap mode lasts until its time is up.
• One small event. An alert carries its kind, the folder's name (never a path), the agent, an ID and two timestamps. That's the whole protocol, and a test fails if anything else would leave.
• Hooks stay out of the way. They print nothing, always exit 0 and hand the send to a detached process, so the agent never waits on the network.
• The app has the last word. It ignores an alert that's expired (alerts live 30 minutes), or one it has already rung for.

Push is best-effort, as on any phone: a phone that's off, offline for a long time, or has the app force-stopped won't ring. With the app, code-alarm status --last shows what happened to the last alert: whether it rang, how long after it was sent, and when you stopped it.

Commands

Command	What it does
code-alarm pair [<code>]	Pair with the Code Alarm app, by QR or by the code the app shows
code-alarm init	Create a private ntfy topic instead, and show how to subscribe
code-alarm test [--notify]	Ring the phone now, or send a plain notification
code-alarm arm [--for 12h] [--notify]	Ring when the agent in this folder next finishes, stops or needs you
code-alarm nap 2h [--notify]	Ring for every session until the time is up
code-alarm disarm [--all]	Cancel arming for this folder, or everything
code-alarm status [--last]	What's set up, what's armed, and the last alerts
code-alarm use ntfy|app	Switch between ntfy and the app when both are set up
code-alarm unpair	Remove this computer from the phone
code-alarm install codex	Add the hooks and skill to Codex (uninstall codex removes them)

code-alarm --help lists every option.

Troubleshooting

• Nothing rings after you reinstalled the app or cleared its data. The phone registered afresh, so this computer's pairing points at the old install. code-alarm status and code-alarm test say so. Pair again with code-alarm pair, and remove the old computer from the app's list.
• Codex stopped alerting after an update. Codex's hooks run their own copy of code-alarm. code-alarm status says when it's out of date, and init, pair, unpair and use refresh it for you.
• Anything else: code-alarm status shows the last alerts and what happened to them. Bugs and ideas are welcome in issues.

Develop

cd cli
npm install
npm run check

npm run check type-checks, runs the tests, and builds the bundle into cli/dist/ and the Claude Code plugin. The bundled files are committed, because plugins install straight from the repository. To try your working copy in Claude Code: claude --plugin-dir plugins/claude-code. The rules for contributors, human or AI, are in AGENTS.md.

License

MIT. Not affiliated with Anthropic or OpenAI.

The CLI bundles Project Nayuki's QR Code generator library (MIT), to draw the pairing QR in the terminal. Its notice is kept in cli/src/vendor/qrcodegen.ts and at the end of the bundle.