npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@delt/claude-alarm

v1.13.0

Published

Monitor and get notifications from multiple Claude Code sessions via MCP Channels

Readme

claude-alarm

Multi-session monitoring dashboard for Claude Code via MCP Channels

Monitor and interact with multiple Claude Code sessions from a web dashboard. Get desktop notifications when tasks complete, send messages to Claude, and track session status.

Architecture

Features

  • Multi-Session Monitoring — Real-time session status (idle / working / waiting)
  • Two-way Messaging — Text + markdown + image exchange with Claude
  • Desktop Notifications — Windows / macOS / Linux toast alerts
  • Telegram Integration — Two-way messaging via Telegram bot
  • Webhook Support — Slack, Discord, or custom webhook endpoints
  • Token Auth — Auto-generated secure access
  • Dark / Light Mode — Theme toggle with persistence
  • Permission Relay — Approve/deny tool calls from dashboard or phone
  • Multi-Machine — Remote hub access support
  • Codex Sessions — See and message OpenAI Codex conversations next to Claude sessions

Quick Start

1. Install

npm install -g @delt/claude-alarm

2. Start the Hub

claude-alarm hub start

3. Initialize Project

cd your-project
claude-alarm init

4. Run Claude Code

claude --dangerously-load-development-channels server:claude-alarm

5. Open Dashboard

Open http://127.0.0.1:7900 in your browser.

Message Flow

Dashboard

Session cards show each Claude session's context size in a chip next to its status, with the change since the last update (for example 312k +4k; hover for the exact count). The channel server reads it from the session's transcript under ~/.claude/projects every 30 seconds. The chip's color follows claude-jev-advisor's levels: gray below its minTokens (250k by default), green from there, yellow with /compact or /clear when the advisor suggests one, and red with the share left once the context is within its redRemainingPct (20% by default) of auto-compact. Red needs the claude-alarm mod (claude-alarm mod install), which reports Claude Code's auto-compact threshold; sessions started before the mod was installed or updated show no red. Links in session messages open in a new tab and show their title, or the decoded address for a bare URL.

Usage limits

A Usage card above the notifications shows how much of the 5-hour and weekly limits Claude and Codex have used, with a bar and the reset time for each (on phones, a short line under the header).

  • Claude: run claude-alarm statusline install once (needs a global install). Claude Code passes its limits to the status line, which saves them for the hub; the status line itself shows 5h 42% · 7d 18%. Values refresh when a session on this PC gets a response, and appear only for subscription accounts. An existing status line is left alone unless you pass --replace.
  • Codex: read from the newest session files in ~/.codex/sessions (or CODEX_HOME); nothing to install.
  • Values come from files on the PC running the hub. The card's last line says how old each reading is; hover a reset time for the full date.

/compact and /clear

The conversation header shows /compact and /clear buttons for a Claude Code session that runs the alarm-control mod. A channel message cannot run slash commands, so a small Claude Code mod that claude-alarm ships runs them inside the session.

  • Run claude-alarm mod install once (needs a global install; claude-alarm init offers it). It adds the mod to CLAUDE_CODE_PLUGIN_DIRS in ~/.claude/settings.json next to any other entries, and only sessions started afterwards load it.
  • The buttons are greyed out while the session is answering; /clear asks for a second press. The result appears in the notifications.
  • With claude-jev-advisor writing its advice, the suggested button is outlined and the session card shows a dot.
  • claude-alarm mod uninstall takes it out again; open sessions keep it until they restart.

CLI Commands

| Command | Description | |---------|-------------| | claude-alarm init | Setup project and show next steps | | claude-alarm hub start [-d] | Start hub server (-d for daemon) | | claude-alarm hub stop | Stop hub daemon | | claude-alarm hub status | Show hub status | | claude-alarm token | Show auth token | | claude-alarm token new | Replace the auth token with a new random one | | claude-alarm token set <token> | Use your own token (16+ characters, no spaces) | | claude-alarm test | Send test notification | | claude-alarm codex enable / disable | Start (or stop starting) the Codex adapter with the hub | | claude-alarm codex start / stop / status | Run the Codex adapter on its own, e.g. when Codex runs on another PC. start tells you whether the adapter reached Codex and whether the hub answers at the configured address; stop and status ask the running adapter itself | | claude-alarm codex run --brief <file\|-> | Hand a task to Codex through the shared daemon and print the result as JSON (--cwd, --thread, --name, --output-schema, --effort, --model, --approval-timeout, --timeout, --yolo; claude-alarm codex run --help explains each option, the result JSON and the exit codes) | | claude-alarm statusline install [--replace] | Report Claude's 5-hour and weekly usage to the dashboard through Claude Code's status line (--replace replaces an existing status line) | | claude-alarm statusline uninstall | Remove it, putting back a status line it replaced | | claude-alarm mod install / uninstall | Add (or remove) the Claude Code mod that lets the dashboard run /compact and /clear |

Tools Available to Claude

| Tool | Description | |------|-------------| | notify | Send a desktop notification (title, message, level) | | reply | Send a message to the dashboard | | ask | Ask the user with buttons; the answer arrives as a channel message | | status | Update session status (idle, working, waiting_input) |

Questions

A question from ask (or from Codex, below) appears as a card in the session's conversation on the dashboard and as a message with a button per option on Telegram.

  • One question: click an option, or type your own answer and press Enter. Several questions: answer each one, then click Send.
  • On Telegram, tap an option, or reply to the question message to type your own answer.
  • Sending the session a plain message instead closes its open questions.
  • A question counts as answered once the session confirms it took the answer; if it could not, the card opens again with the reason.
  • ask sets the session to waiting input; once its last open question is answered, the hub sets it back to working.
  • After updating claude-alarm, restart the hub (claude-alarm hub stop, then claude-alarm hub start) so the sessions and the hub run the same version. An older hub cannot show questions; ask then tells Claude to ask with reply instead.

Configuration

Config stored at ~/.claude-alarm/config.json:

{
  "hub": {
    "host": "127.0.0.1",
    "port": 7900,
    "token": "auto-generated-uuid"
  },
  "notifications": {
    "desktop": true,
    "sound": true
  },
  "webhooks": [],
  "telegram": {
    "botToken": "",
    "chatId": "",
    "enabled": false
  }
}

Custom Session Names

{
  "mcpServers": {
    "claude-alarm": {
      "command": "npx",
      "args": ["-y", "@delt/claude-alarm", "serve"],
      "env": {
        "CLAUDE_ALARM_SESSION_NAME": "my-project"
      }
    }
  }
}

Webhooks

Configure via dashboard (⚙ Settings → Webhook tab) or in config:

{
  "webhooks": [
    {
      "url": "https://hooks.slack.com/services/...",
      "headers": { "Content-Type": "application/json" }
    }
  ]
}

Telegram Bot

Two-way messaging with Claude sessions via Telegram — text and images.

Setup (guided wizard in dashboard):

  1. Create a bot with @BotFather on Telegram
  2. Open dashboard → ⚙ Settings → Telegram tab
  3. Step 1: Paste your Bot Token → Next
  4. Step 2: Send any message to your bot, then click Detect Chat ID → select your chat → Next
  5. Step 3: Send Test → Save

Features:

  • Notifications forwarded to Telegram with session labels
  • Reply to a notification → routed to the correct session
  • Send a new message → auto-delivered if 1 session, or pick from a list
  • Send photos from Telegram → downloaded and forwarded to Claude
  • Photo captions included as text alongside the image
  • Markdown links in session messages arrive as tappable links that show their title
{
  "telegram": {
    "botToken": "123456:ABC-DEF...",
    "chatId": "your-chat-id",
    "enabled": true
  }
}

Codex Sessions

claude-alarm can show OpenAI Codex conversations on the dashboard and in Telegram, next to your Claude sessions.

claude-alarm codex enable
claude-alarm hub stop
claude-alarm hub start

claude-alarm init also offers this once when it finds codex (on PATH, or on Windows in the standard install locations below). Your answer is saved, and codex enable / codex disable change it later.

  • Requires the Codex CLI with its app-server daemon. The Codex adapter runs codex app-server daemon start when it starts (with the hub, or with claude-alarm codex start), so the daemon comes up after a reboot too; if it stops later, run that command or restart the adapter. On Windows, when codex is not on PATH, the adapter also looks in the standard install locations (%LOCALAPPDATA%\Programs\OpenAI\Codex\bin\codex.exe, then %APPDATA%\npm\codex.cmd). Anywhere else, set "codex": { "command": "C:/path/to/codex.exe" } in ~/.claude-alarm/config.json.
  • If codex cannot be found at all, the hub sends one Codex not found notification (desktop and webhooks) and the console keeps printing Codex daemon connection failed: spawn codex ENOENT. A terminal opened before Codex was installed still has the old PATH, so open a new terminal and restart the hub, or set codex.command.
  • Every loaded Codex conversation appears as a session with a Codex badge. Replies, failures and approval requests are relayed to the dashboard and Telegram.
  • Conversations started by claude-alarm codex run are the exception: the session that ran it already gets the result, so their replies and failures show only on the dashboard, with no desktop or Telegram notification. Approval requests still reach Telegram. If you message such a conversation from the dashboard or Telegram yourself, the answer to that message is relayed as usual. Both the hub and the Codex adapter need this version; codex run from an older version does not mark its conversations.
  • Messages you send show up in Codex prefixed with [claude-alarm · Dashboard] or [claude-alarm · Telegram]. If Codex is idle they start a new task; if it is working they join the current task and Codex reads them after its current step (you get a Queued notice). While Codex waits for an approval or for your answer, messages are not delivered; answer that first.
  • Images work the same way: paste, drag & drop or 📎 on the dashboard, or send a photo to the Telegram bot (PNG, JPEG, GIF or WebP). The Codex adapter must run on the same PC as the hub to read them.
  • Approvals for commands, file changes and MCP tools can be answered from the dashboard or Telegram with the choices Codex offers (for example Allow once, Always allow this command, Cancel task). Whoever answers first wins, in Codex or here; the other buttons close as Resolved, which does not say what was chosen. Buttons from before a hub or adapter restart show Expired; if Codex is still waiting, a new request appears.
  • After updating claude-alarm, reload open dashboard tabs so they pick up the changes.
  • Questions Codex asks during a task (app-server 0.160) show as question cards on the dashboard and with buttons on Telegram (see Questions); the answer goes back into that task, or starts a new one if it has ended. Questions Codex asks through requestUserInput still have to be answered in Codex; claude-alarm tells you one is waiting.
  • A conversation is followed only while Codex is working on it, so a closed Codex window drops off the dashboard about a minute later. If a reply could not be picked up, you get a Reply not relayed warning; read it in the Codex window. Conversations created from the dashboard are the exception (below).
  • If Codex runs on another PC, run claude-alarm codex start there. It reads the hub address and token from that PC's ~/.claude-alarm/config.json (hub.host, hub.port, hub.token) or from CLAUDE_ALARM_HUB_HOST, CLAUDE_ALARM_HUB_PORT and CLAUDE_ALARM_HUB_TOKEN; the remote-hub answers you give claude-alarm init go only into that project's .mcp.json and do not apply here. codex start says whether it reached Codex and the hub. Keep claude-alarm at the same version on both PCs; an older hub cannot show Codex's choices.
  • Only one Codex adapter runs per user. A second one finds the first and stops (codex start says already running); an adapter the hub starts waits instead and takes over shortly after the other one stops. claude-alarm codex stop stops the adapter that is running now. If that was the hub's own adapter, the hub does not start it again until you restart the hub; to turn Codex off for good, use codex disable and restart the hub. claude-alarm 1.2.0 and earlier tracked the adapter in ~/.claude-alarm/codex.pid; that file is no longer used, and codex start and codex status point it out if it names a running process.
  • New Codex conversation from the dashboard: click + in the session list. The Codex part appears only when a Codex adapter is connected to a running Codex daemon. Pick the PC if more than one is connected, type a folder on that PC or pick one of its recent Codex folders, and click Create. The new session is selected; send the first instruction from the message box.
  • Conversations created this way run with full access and no approval prompts (danger-full-access, approval policy never): Codex can run any command on that PC.
  • They stay on the dashboard until you close them with the session's × button (tap it, then tap Close? again). Closing only lets go of the conversation: it stays in Codex's history and can be continued in Codex. If Codex is still working, the task finishes first and the session drops off about a minute later. When the hub restarts, an adapter started by the hub restarts with it and these conversations drop off about a minute later.

Permission Relay

Approve or deny Claude's tool calls remotely — from the dashboard or your phone — without --dangerously-skip-permissions.

When Claude wants to run a tool (Bash, Write, Edit, etc.), a permission request appears on the dashboard with Allow / Deny buttons. Keyboard shortcuts: Enter = Allow, Esc = Deny.

  • Works with Claude Code v2.1.81+
  • No extra setup needed — automatically enabled
  • Local terminal prompt stays open; whichever answer arrives first (local or dashboard) is applied
  • Parsed previews: Bash commands show $ command, file operations show file paths

Authentication

Every connection to the hub needs the hub token — including ones from the same machine.

  • Channel servers read it from ~/.claude-alarm/config.json automatically (or CLAUDE_ALARM_HUB_TOKEN).
  • Dashboard: open the login link printed by claude-alarm hub start (http://127.0.0.1:7900/?token=…), or paste the token from claude-alarm token into the login form. The browser keeps an HttpOnly cookie for 30 days, and the token is removed from the URL.
  • CLI / scripts: send Authorization: Bearer <token>.

Changing the token

  1. On the hub machine run claude-alarm token new (or claude-alarm token set <token>), then restart the hub: claude-alarm hub stop, claude-alarm hub start -d.
  2. On every other machine that connects to this hub run claude-alarm token set <the new token>.
  3. Open the dashboard with the new login link; the old cookie no longer works.

Running Claude sessions and Codex adapters that read the token from config.json pick up the new one when they reconnect, so they do not need a restart. Ones started with CLAUDE_ALARM_HUB_TOKEN (for example from a .mcp.json written by claude-alarm init) keep that value: update or remove it there and restart the session.

Upgrading from 0.9.x: a local session that sets CLAUDE_ALARM_HUB_TOKEN to a different value than the hub's token no longer connects. Scripts that called the local API without a token now get 401.

Remote Access

Anyone who can open the dashboard can start Codex conversations with full access on every PC that runs the Codex adapter. Keep the hub token private.

Pick one:

  1. Tailscale (recommended) — set host to the hub machine's Tailscale IP and use that address from other machines. Traffic is encrypted and never exposed to the internet.

  2. Cloudflare Tunnel / nginx with HTTPS — keep host: "127.0.0.1" and point the tunnel or proxy at http://127.0.0.1:7900. The proxy must keep the browser's Host header (the hub rejects requests whose Origin doesn't match it), pass WebSocket upgrades, and forward X-Forwarded-Proto so the dashboard cookie is marked Secure. For nginx:

    location / {
      proxy_pass http://127.0.0.1:7900;
      proxy_http_version 1.1;
      proxy_set_header Host $host;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection "upgrade";
      proxy_set_header X-Forwarded-Proto $scheme;
    }
  3. Direct 0.0.0.0 — set host to 0.0.0.0 and open port 7900. Traffic, including the token, is plain HTTP: use only on networks you trust.

On the remote machine run claude-alarm init → select remote hub (Y), or configure:

{
  "mcpServers": {
    "claude-alarm": {
      "command": "npx",
      "args": ["-y", "@delt/claude-alarm", "serve"],
      "env": {
        "CLAUDE_ALARM_HUB_HOST": "your-hub-address",
        "CLAUDE_ALARM_HUB_PORT": "7900",
        "CLAUDE_ALARM_HUB_TOKEN": "your-token"
      }
    }
  }
}

Mentioning Other Sessions

In the dashboard input, type @<session name> to have the selected session send something to another session through Claude Code's built-in SendMessage:

@front The UserVo response gained a deptNm field — let them know
  • Names are the ones shown in the dashboard (your custom name, or the folder name). Names with spaces are written @[my name].
  • The dashboard resolves each mention to the target's SendMessage name and appends a routing line. A mention that looks like a session name but doesn't resolve to exactly one local session blocks the send; other @words (e.g. @Override, code spans) are left alone.
  • Only sessions on the hub's machine can be mentioned.
  • Messages exchanged between sessions are not shown in the dashboard.
  • Requires Claude Code with cross-session messaging (2.1.239+ on Windows).

Image Support

Dashboard (local sessions):

  • Ctrl+V — Paste from clipboard
  • Drag & Drop — Drop image onto message area
  • Attach button — Click 📎 to browse files
  • Images + text sent together as one message

Telegram:

  • Send photos to the bot → forwarded to the Claude or Codex session
  • Photo captions included as text

Dashboard images are only available for local sessions (same machine as Hub). Max 10MB, auto-deleted after 5 minutes.

Platform Support

| Platform | Notifications | Engine | |----------|:---:|--------| | Windows | ✓ | SnoreToast | | macOS | ✓ | terminal-notifier | | Linux | ✓ | notify-send |

Requirements

  • Node.js >= 18
  • Claude Code with MCP Channels support
  • Optional, for Codex sessions: OpenAI Codex CLI with the app-server daemon (tested with 0.159.3; approvals, steering and images also with app-server 0.160.0)

License

MIT