claude-remote-approver 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,210 @@
+# claude-remote-approver
+
+Approve or deny Claude Code permission prompts from your phone.
+
+---
+
+## Problem
+
+Claude Code asks for permission before running tools like `Bash`, `Write`, and `Edit`. These prompts require you to be sitting at your terminal. If you step away, Claude Code stalls until you come back and press "y".
+
+**claude-remote-approver** sends each permission prompt as a push notification to your phone via [ntfy.sh](https://ntfy.sh). You tap **Approve** or **Deny**, and Claude Code continues immediately -- no terminal required.
+
+## How it works
+
+```
+Claude Code
+  │
+  │  PermissionRequest hook (stdin JSON)
+  ▼
+hook.mjs
+  │
+  ├──POST──▶ ntfy.sh/<topic>          ──push──▶  Phone (ntfy app)
+  │                                                 │
+  │                                           Approve / Deny tap
+  │                                                 │
+  └──SSE───▶ ntfy.sh/<topic>-response  ◀──POST──┘
+  │
+  │  stdout JSON: { "behavior": "allow" } or { "behavior": "deny" }
+  ▼
+Claude Code continues or stops
+```
+
+1. Claude Code invokes the hook, piping the tool request as JSON to stdin.
+2. `hook.mjs` sends a notification to your ntfy topic with **Approve** and **Deny** action buttons.
+3. The hook subscribes to a response topic (`<topic>-response`) via server-sent events.
+4. When you tap a button on your phone, ntfy.sh publishes your decision to the response topic.
+5. The hook reads the decision, writes `{"behavior":"allow"}` or `{"behavior":"deny"}` to stdout, and exits.
+6. Claude Code proceeds accordingly.
+
+## Quick Start
+
+```bash
+# 1. Install the ntfy app on your phone
+#    iOS: https://apps.apple.com/app/ntfy/id1625396347
+#    Android: https://play.google.com/store/apps/details?id=io.heckel.ntfy
+
+# 2. Install claude-remote-approver
+npm install -g claude-remote-approver
+
+# 3. Run setup
+claude-remote-approver setup
+```
+
+Setup prints a topic name. Subscribe to that topic in the ntfy app, and you are done.
+
+## Installation
+
+```bash
+npm install -g claude-remote-approver
+```
+
+Requires Node.js 18 or later.
+
+## Setup
+
+```bash
+claude-remote-approver setup
+```
+
+This command does three things:
+
+1. **Generates a unique topic** -- a random string like `cra-a1b2c3d4e5f6...` (128 bits of entropy).
+2. **Creates a config file** at `~/.claude-remote-approver.json` with your topic and default settings. The file is created with permission `0600` (owner read/write only).
+3. **Registers the hook** in Claude Code's `~/.claude/settings.json` under `hooks.PermissionRequest`. If a previous hook entry from this tool exists, it is replaced.
+
+After running setup, open the ntfy app on your phone and subscribe to the topic printed in the terminal.
+
+## Usage
+
+### `setup`
+
+Configure the tool and register the hook with Claude Code.
+
+```bash
+claude-remote-approver setup
+# Setup complete. Topic: cra-<hex>
+```
+
+### `test`
+
+Send a test notification to verify your setup is working.
+
+```bash
+claude-remote-approver test
+# Test notification sent successfully.
+```
+
+If you see the notification on your phone, everything is configured correctly.
+
+### `status`
+
+Display the current configuration.
+
+```bash
+claude-remote-approver status
+# Topic:   cra-a1b2c3d4...
+# Server:  https://ntfy.sh
+# Timeout: 120s
+```
+
+### `hook`
+
+Internal command. Claude Code calls this automatically via the registered hook. It reads a JSON payload from stdin and writes a decision to stdout. You do not need to run this manually.
+
+### Flags
+
+```
+--help, -h       Show usage information
+--version, -v    Print version number
+```
+
+## Configuration
+
+Config file location: `~/.claude-remote-approver.json`
+
+```json
+{
+  "topic": "cra-a1b2c3d4e5f67890abcdef1234567890",
+  "ntfyServer": "https://ntfy.sh",
+  "timeout": 120,
+  "autoApprove": [],
+  "autoDeny": []
+}
+```
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `topic` | `string` | `""` | Your unique ntfy topic. Generated by `setup`. |
+| `ntfyServer` | `string` | `"https://ntfy.sh"` | The ntfy server URL. Change this if you self-host. |
+| `timeout` | `number` | `120` | Seconds to wait for a response before auto-denying. |
+| `autoApprove` | `string[]` | `[]` | Reserved for future use. |
+| `autoDeny` | `string[]` | `[]` | Reserved for future use. |
+
+### Using a self-hosted ntfy server
+
+Edit `~/.claude-remote-approver.json` and set `ntfyServer` to your server URL:
+
+```json
+{
+  "ntfyServer": "https://ntfy.example.com"
+}
+```
+
+Then subscribe to the topic on your self-hosted server in the ntfy app.
+
+## How ntfy.sh works
+
+[ntfy.sh](https://ntfy.sh) is a simple HTTP-based pub-sub notification service. Any client can publish a message to a topic by sending a POST request, and any client subscribed to that topic receives the message as a push notification.
+
+claude-remote-approver uses two topics:
+
+- **`<topic>`** -- The hook publishes permission requests here. Your phone receives these as notifications with action buttons.
+- **`<topic>-response`** -- When you tap Approve or Deny, the ntfy app sends an HTTP POST to this topic. The hook subscribes to it via SSE (server-sent events) and reads your decision.
+
+No account is required. Topics are identified by name only, which is why the generated topic contains 128 bits of randomness.
+
+For more details, see the [ntfy documentation](https://docs.ntfy.sh).
+
+## Security
+
+### Topic entropy
+
+The topic name is generated using `crypto.randomBytes(16)`, producing 128 bits of randomness (32 hex characters). This makes the topic effectively unguessable.
+
+### File permissions
+
+The config file (`~/.claude-remote-approver.json`) is written with mode `0600` -- only the file owner can read or write it. This prevents other users on the system from reading your topic name.
+
+### Self-hosting recommendation
+
+The public ntfy.sh server is convenient but means your permission request details (tool names, commands, file paths) pass through a third-party server. For sensitive work, consider [self-hosting ntfy](https://docs.ntfy.sh/install/) and setting `ntfyServer` in your config to your own server.
+
+### Timeout behavior
+
+If no response is received within the configured timeout (default: 120 seconds), the hook automatically **denies** the request. This fail-closed design ensures Claude Code does not proceed without explicit approval.
+
+## Disclaimer
+
+**Use at your own risk.** This tool automates permission control for Claude Code. Misuse or misconfiguration may result in unintended code execution, file modification, or data loss.
+
+The authors are not responsible for any damages or losses arising from the use of this tool, including but not limited to:
+
+- Accidental approval of dangerous commands (e.g., mistapping Approve on your phone)
+- Unintended denial of safe commands (e.g., timeout, network issues)
+- Security breaches if the topic name is compromised
+
+**Not a substitute for careful review.** The push notification shows the tool name and a brief summary, but not the full context of what Claude Code is doing. Always review what you are approving.
+
+This software is provided "AS IS" without warranty of any kind, as stated in the [MIT License](LICENSE).
+
+## Requirements
+
+- **Node.js** >= 18.0.0
+- **ntfy app** on your phone
+  - [iOS (App Store)](https://apps.apple.com/app/ntfy/id1625396347)
+  - [Android (Google Play)](https://play.google.com/store/apps/details?id=io.heckel.ntfy)
+
+## License
+
+[MIT](LICENSE)

package/bin/cli.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+
+/**
+ * CLI entry point for claude-remote-approver.
+ *
+ * Subcommands: setup | test | status | hook
+ * All I/O goes through the injected `deps` object so the module is fully testable.
+ */
+
+import { fileURLToPath } from "node:url";
+import { realpathSync } from "node:fs";
+
+// ---------------------------------------------------------------------------
+// main
+// ---------------------------------------------------------------------------
+
+export async function main(args, deps) {
+  if (args.includes("--help") || args.includes("-h")) {
+    deps.stdout.write("Usage: claude-remote-approver <command>\n\nCommands:\n  setup   Set up remote approval\n  test    Send a test notification\n  status  Show current configuration\n  hook    Process a Claude Code hook (internal)\n");
+    return;
+  }
+  if (args.includes("--version") || args.includes("-v")) {
+    deps.stdout.write("0.1.0\n");
+    return;
+  }
+
+  const command = args[0];
+
+  switch (command) {
+    case "setup": {
+      const result = await deps.runSetup(deps);
+      deps.stdout.write(`Setup complete. Topic: ${result.topic}\n`);
+      break;
+    }
+
+    case "test": {
+      const config = deps.loadConfig();
+      if (!config.topic) {
+        deps.stderr.write("Error: No topic configured. Run 'claude-remote-approver setup' first.\n");
+        break;
+      }
+      try {
+        await deps.sendNotification({
+          server: config.ntfyServer,
+          topic: config.topic,
+          title: "Claude Remote Approver",
+          message: "Test notification - if you see this, setup is working!",
+          actions: [],
+          requestId: "test",
+        });
+        deps.stdout.write("Test notification sent successfully.\n");
+      } catch (err) {
+        deps.stderr.write(`Error: Failed to send notification: ${err.message}\n`);
+      }
+      break;
+    }
+
+    case "status": {
+      const config = deps.loadConfig();
+      deps.stdout.write(`Topic:   ${config.topic}\n`);
+      deps.stdout.write(`Server:  ${config.ntfyServer}\n`);
+      deps.stdout.write(`Timeout: ${config.timeout}s\n`);
+      break;
+    }
+
+    case "hook": {
+      let input;
+      try {
+        input = JSON.parse(deps.stdin);
+      } catch {
+        const deny = { hookSpecificOutput: { decision: { behavior: "deny" } } };
+        deps.stdout.write(JSON.stringify(deny) + "\n");
+        break;
+      }
+
+      let result;
+      try {
+        result = await deps.processHook(input, deps);
+      } catch {
+        const deny = { hookSpecificOutput: { decision: { behavior: "deny" } } };
+        deps.stdout.write(JSON.stringify(deny) + "\n");
+        break;
+      }
+
+      deps.stdout.write(JSON.stringify(result) + "\n");
+      break;
+    }
+
+    default: {
+      deps.stderr.write(
+        "Usage: claude-remote-approver <command>\n\nCommands:\n  setup   Configure topic and register hook\n  test    Send a test notification\n  status  Show current configuration\n  hook    Process a Claude Code hook (reads JSON from stdin)\n",
+      );
+      deps.exit(1);
+      break;
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Auto-execute when run directly (not imported)
+// ---------------------------------------------------------------------------
+
+const isMain =
+  typeof process !== "undefined" &&
+  process.argv[1] &&
+  (() => {
+    try {
+      return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
+    } catch {
+      return false;
+    }
+  })();
+
+if (isMain) {
+  const { loadConfig, saveConfig, generateTopic } = await import(
+    "../src/config.mjs"
+  );
+  const { sendNotification, waitForResponse, formatToolInfo } = await import(
+    "../src/ntfy.mjs"
+  );
+  const { processHook } = await import("../src/hook.mjs");
+  const { runSetup } = await import("../src/setup.mjs");
+
+  const args = process.argv.slice(2);
+
+  let stdinData = "";
+  if (!process.stdin.isTTY) {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk);
+    }
+    stdinData = Buffer.concat(chunks).toString("utf-8");
+  }
+
+  const deps = {
+    loadConfig,
+    saveConfig,
+    generateTopic,
+    sendNotification,
+    waitForResponse,
+    formatToolInfo,
+    processHook,
+    runSetup,
+    stdout: process.stdout,
+    stderr: process.stderr,
+    stdin: stdinData,
+    exit: process.exit,
+  };
+
+  await main(args, deps);
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "claude-remote-approver",
+  "version": "0.1.0",
+  "description": "Approve or deny Claude Code permission prompts remotely from your phone via ntfy.sh",
+  "type": "module",
+  "bin": {
+    "claude-remote-approver": "./bin/cli.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/**/*.test.mjs"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "remote",
+    "approval",
+    "ntfy",
+    "notification",
+    "hook"
+  ],
+  "author": "Yuuichi Eguchi",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eguchiyuuichi/claude-remote-approver.git"
+  }
+}

package/src/config.mjs

@@ -0,0 +1,42 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import crypto from "node:crypto";
+
+export const CONFIG_PATH = path.join(os.homedir(), ".claude-remote-approver.json");
+
+export const DEFAULT_CONFIG = {
+  topic: "",
+  ntfyServer: "https://ntfy.sh",
+  timeout: 120,
+  // autoApprove/autoDeny are reserved for future use and not yet implemented
+  autoApprove: [],
+  autoDeny: [],
+};
+
+export function loadConfig(configPath = CONFIG_PATH) {
+  try {
+    const raw = fs.readFileSync(configPath, "utf-8");
+    const fileConfig = JSON.parse(raw);
+    const config = { ...DEFAULT_CONFIG, ...fileConfig };
+    if (typeof config.topic !== "string") config.topic = DEFAULT_CONFIG.topic;
+    if (typeof config.ntfyServer !== "string") config.ntfyServer = DEFAULT_CONFIG.ntfyServer;
+    if (typeof config.timeout !== "number" || config.timeout <= 0) config.timeout = DEFAULT_CONFIG.timeout;
+    if (!Array.isArray(config.autoApprove)) config.autoApprove = DEFAULT_CONFIG.autoApprove;
+    if (!Array.isArray(config.autoDeny)) config.autoDeny = DEFAULT_CONFIG.autoDeny;
+    return config;
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return { ...DEFAULT_CONFIG };
+    }
+    throw err;
+  }
+}
+
+export function saveConfig(config, configPath = CONFIG_PATH) {
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2), { mode: 0o600 });
+}
+
+export function generateTopic() {
+  return `cra-${crypto.randomBytes(16).toString("hex")}`;
+}

package/src/hook.mjs

@@ -0,0 +1,84 @@
+// src/hook.mjs
+
+import crypto from "node:crypto";
+
+/**
+ * Build ntfy action buttons for Approve / Deny.
+ *
+ * @param {string} server - ntfy server URL
+ * @param {string} topic - ntfy topic
+ * @param {string} requestId - Unique request identifier
+ * @returns {Array<object>} Array of 2 action objects
+ */
+export function buildActions(server, topic, requestId) {
+  const url = `${server}/${topic}-response`;
+  return [
+    {
+      action: "http",
+      label: "Approve",
+      url,
+      body: JSON.stringify({ requestId, approved: true }),
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+    },
+    {
+      action: "http",
+      label: "Deny",
+      url,
+      body: JSON.stringify({ requestId, approved: false }),
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+    },
+  ];
+}
+
+/**
+ * Process a Claude Code hook request.
+ *
+ * @param {object} input - The hook input payload
+ * @param {object} deps - Injected dependencies
+ * @param {Function} deps.loadConfig
+ * @param {Function} deps.sendNotification
+ * @param {Function} deps.waitForResponse
+ * @param {Function} deps.formatToolInfo
+ * @returns {Promise<object>} Decision JSON
+ */
+export async function processHook(input, { loadConfig, sendNotification, waitForResponse, formatToolInfo }) {
+  const config = loadConfig();
+
+  if (!config.topic) {
+    return { hookSpecificOutput: { decision: { behavior: "deny" } } };
+  }
+
+  const requestId = crypto.randomUUID();
+  const { title, message } = formatToolInfo(input);
+  const actions = buildActions(config.ntfyServer, config.topic, requestId);
+
+  try {
+    await sendNotification({
+      server: config.ntfyServer,
+      topic: config.topic,
+      title,
+      message,
+      actions,
+      requestId,
+    });
+  } catch {
+    return { hookSpecificOutput: { decision: { behavior: "deny" } } };
+  }
+
+  let response;
+  try {
+    response = await waitForResponse({
+      server: config.ntfyServer,
+      topic: config.topic,
+      requestId,
+      timeout: config.timeout * 1000,
+    });
+  } catch {
+    return { hookSpecificOutput: { decision: { behavior: "deny" } } };
+  }
+
+  const behavior = response.approved ? "allow" : "deny";
+  return { hookSpecificOutput: { decision: { behavior } } };
+}

package/src/ntfy.mjs

@@ -0,0 +1,119 @@
+// src/ntfy.mjs
+
+/**
+ * Send a push notification via ntfy.
+ *
+ * @param {{ server: string, topic: string, title: string, message: string, actions: unknown[], requestId: string }} params
+ * @returns {Promise<Response>}
+ */
+export async function sendNotification({ server, topic, title, message, actions, requestId }) {
+  const baseUrl = server.replace(/\/+$/, '');
+  const url = `${baseUrl}/${topic}`;
+
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ topic, title, message, actions }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`ntfy notification failed: HTTP ${response.status}`);
+  }
+
+  return response;
+}
+
+/**
+ * Subscribe to the response topic via SSE and wait for a matching requestId.
+ *
+ * @param {{ server: string, topic: string, requestId: string, timeout: number }} params
+ * @returns {Promise<{ approved: boolean }>}
+ */
+export async function waitForResponse({ server, topic, requestId, timeout }) {
+  const baseUrl = server.replace(/\/+$/, '');
+  const url = `${baseUrl}/${topic}-response/json`;
+
+  const controller = new AbortController();
+
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let timer;
+
+  try {
+    const response = await fetch(url, { signal: controller.signal });
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+
+    // Listen to abort so we can cancel the reader even when the mock stream
+    // never closes (the real fetch would propagate the signal, but mocks may not).
+    const onAbort = () => reader.cancel();
+    controller.signal.addEventListener('abort', onAbort);
+
+    // Start the timeout AFTER fetch resolves so we measure waiting time only.
+    timer = setTimeout(() => controller.abort(), timeout);
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop();
+
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          try {
+            const event = JSON.parse(line);
+            const parsed = JSON.parse(event.message);
+            if (parsed.requestId === requestId) {
+              clearTimeout(timer);
+              controller.signal.removeEventListener('abort', onAbort);
+              return { approved: parsed.approved };
+            }
+          } catch {
+            // skip non-JSON lines
+          }
+        }
+      }
+    } finally {
+      controller.signal.removeEventListener('abort', onAbort);
+    }
+
+    clearTimeout(timer);
+    return { approved: false };
+  } catch (err) {
+    if (timer !== undefined) clearTimeout(timer);
+    if (err?.name !== "AbortError") {
+      console.error("[claude-remote-approver] waitForResponse error:", err);
+    }
+    return { approved: false };
+  }
+}
+
+/**
+ * Format tool information for display in the notification.
+ *
+ * @param {{ hookName: string, toolName: string, toolInput: Record<string, unknown> }} params
+ * @returns {{ title: string, message: string }}
+ */
+export function formatToolInfo({ hookName, toolName, toolInput }) {
+  const title = `Claude Code: ${toolName}`;
+  let message;
+
+  switch (toolName) {
+    case 'Bash':
+      message = toolInput?.command ?? JSON.stringify(toolInput);
+      break;
+    case 'Read':
+    case 'Write':
+    case 'Edit':
+      message = toolInput?.file_path ?? JSON.stringify(toolInput);
+      break;
+    default:
+      message = JSON.stringify(toolInput);
+      break;
+  }
+
+  return { title, message };
+}

package/src/setup.mjs

@@ -0,0 +1,75 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Returns the hook command string: `node <absolute_path_to_src/hook.mjs>`
+ */
+export function getHookCommand() {
+  const hookPath = path.resolve(import.meta.dirname, "hook.mjs");
+  return `node "${hookPath}"`;
+}
+
+/**
+ * Registers the PermissionRequest hook in Claude's settings.json.
+ * Creates the file if it does not exist. Preserves all existing settings and hooks.
+ */
+export function registerHook(settingsPath, hookCommand) {
+  let settings = {};
+
+  try {
+    const raw = fs.readFileSync(settingsPath, "utf-8");
+    settings = JSON.parse(raw);
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      throw err;
+    }
+  }
+
+  if (!settings.hooks) {
+    settings.hooks = {};
+  }
+
+  if (!Array.isArray(settings.hooks.PermissionRequest)) {
+    settings.hooks.PermissionRequest = [];
+  }
+
+  const existingIndex = settings.hooks.PermissionRequest.findIndex(
+    (h) => h.command && h.command.includes("claude-remote-approver")
+  );
+
+  const hookEntry = { type: "command", command: hookCommand };
+
+  if (existingIndex >= 0) {
+    settings.hooks.PermissionRequest[existingIndex] = hookEntry;
+  } else {
+    settings.hooks.PermissionRequest.push(hookEntry);
+  }
+
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+}
+
+/**
+ * Runs the full setup flow:
+ * 1. Generate a topic
+ * 2. Build and save config
+ * 3. Register the hook in settings.json
+ * 4. Return { topic, configPath, settingsPath }
+ */
+export async function runSetup({
+  configPath,
+  settingsPath,
+  generateTopic,
+  saveConfig,
+  loadConfig,
+}) {
+  const topic = generateTopic();
+
+  const config = loadConfig(configPath);
+  config.topic = topic;
+  saveConfig(config, configPath);
+
+  const hookCommand = getHookCommand();
+  registerHook(settingsPath, hookCommand);
+
+  return { topic, configPath, settingsPath };
+}