clawleash 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do
+          not modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text from the Work, provided that such
+          additional attribution notices cannot be construed as modifying
+          the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 clawleash contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,143 @@
+# 🦀 clawleash — approve Claude Code from your phone
+
+[![npm](https://img.shields.io/npm/v/clawleash.svg)](https://www.npmjs.com/package/clawleash)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
+[![Tailscale ready](https://img.shields.io/badge/Tailscale-ready-7b61ff.svg)](#connectivity)
+
+> **clawleash is an open-source CLI that lets you approve or deny Claude Code permission prompts from your phone — so long autonomous runs never stall while you're away from the desk.** Self-hosted and token-gated, it reaches your Mac over Tailscale or the same Wi‑Fi. No cloud relay, no account, no subscription.
+
+```bash
+npx clawleash
+```
+
+That's it. Scan the printed URL on your phone, tap **Allow** or **Deny**, and your agent keeps moving.
+
+---
+
+## The problem
+
+You kick off a big refactor, grab a coffee, come back ten minutes later — and Claude Code has been sitting idle the whole time, **stuck waiting for permission to run `mkdir`**. Long autonomous runs stall on a single prompt the moment you step away from the keyboard.
+
+`clawleash` puts that Allow/Deny button in your pocket.
+
+## Quick start
+
+```bash
+# In any terminal on the machine where you run Claude Code:
+npx clawleash
+```
+
+On first run it:
+
+1. Installs Claude Code hooks into `~/.claude/settings.json` (idempotent, removable).
+2. Starts a tiny local server and prints a **phone URL** (Tailscale first, then LAN).
+
+Open that URL on your phone → **Add to Home Screen** → done. Next time Claude Code asks for permission while you're away, the prompt shows up on your phone with **Allow / Deny** buttons.
+
+```bash
+npx clawleash url        # print the phone URL(s) again
+npx clawleash uninstall  # remove the hooks
+```
+
+## How it works
+
+```
+Claude Code (CLI)
+  │  PermissionRequest hook (http, blocks up to 600s)   ─────────────┐
+  │  SessionStart / PreToolUse / Stop … (status)        ──────────┐  │
+  ▼                                                               ▼  ▼
+                                    clawleash daemon (local, 0.0.0.0:4271)
+                                      ├─ holds the request open until you answer
+                                      ├─ token-gated phone page (installable PWA)
+                                      └─ optional ntfy push
+  phone ◀──── Tailscale / same Wi-Fi ────┘   tap Allow / Deny
+```
+
+The `PermissionRequest` hook **blocks** while clawleash holds the HTTP request open. Your phone tap returns the decision (`allow` / `deny`) to Claude Code, which then proceeds or blocks the tool. If nobody answers before the timeout, it **falls back to the normal terminal prompt** — so an offline phone never wedges your session.
+
+## Connectivity
+
+| Where you are | What to use | Setup |
+| --- | --- | --- |
+| Same Wi‑Fi (at home/office) | the LAN URL (`192.168.x…`) | none — works immediately |
+| Out and about | the Tailscale URL (`100.x…`) | install [Tailscale](https://tailscale.com) on your Mac **and** phone, same account, same tailnet |
+
+**Push notifications (optional):** set an [ntfy](https://ntfy.sh) topic and subscribe to it in the ntfy app to get pinged the moment a prompt needs you.
+
+## clawleash vs the alternatives
+
+| | **clawleash** | ntfy-only hook | Anthropic Remote Control | clawd-on-desk |
+| --- | :---: | :---: | :---: | :---: |
+| Approve/Deny from phone | ✅ | ❌ (notify only) | ✅ | ✅ |
+| Live agent status on phone | ✅ | ❌ | partial | ✅ |
+| Self-hosted, no cloud relay | ✅ | ✅ | ❌ | ✅ |
+| Tailscale / LAN (no public exposure) | ✅ | n/a | ❌ | ✅ |
+| One-command `npx` install | ✅ | manual | n/a | ❌ (desktop app) |
+| Headless / GUI-free | ✅ | ✅ | ✅ | ❌ |
+| Needs a Claude subscription/tier | ❌ | ❌ | varies | ❌ |
+
+## Configuration
+
+Config lives in `~/.config/clawleash/config.json` (or the OS equivalent):
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `token` | random | secret in the phone URL (`?k=…`) |
+| `port` | `4271` | daemon port (`CLAWLEASH_PORT` env overrides) |
+| `approvals` | `true` | mirror permission prompts to the phone |
+| `ntfyTopic` | `""` | ntfy topic for push (empty = off) |
+
+## Security & threat model
+
+- **Off by default for outsiders.** Every phone-facing route is gated by a secret token; without `?k=<token>` you get a `403`.
+- **Hook ingress is loopback-only.** `/hook/*` rejects any request that isn't from `127.0.0.1`.
+- **You only resolve existing prompts.** The phone can tap Allow/Deny on a prompt Claude Code already raised — it cannot inject arbitrary commands.
+- **Headless sessions** (`claude -p`) are not eligible, and **no response → fall back** to the terminal prompt. An offline phone never blocks you.
+- **Keep it on your tailnet.** Prefer Tailscale (private mesh) over exposing the port publicly.
+
+## FAQ
+
+### How do I approve Claude Code permission requests from my phone?
+Run `npx clawleash` on the machine running Claude Code, open the printed URL on your phone, and tap Allow/Deny when a prompt appears.
+
+### Can I control Claude Code remotely from my phone?
+Yes — clawleash mirrors permission prompts and live agent status to a phone web page over your own Tailscale network or LAN.
+
+### Do I need a Claude subscription or Anthropic's Remote Control?
+No. clawleash is self-hosted and works with your local Claude Code CLI; nothing runs in the cloud.
+
+### Is it safe to approve Claude Code permissions from my phone?
+The page is token-gated, hook ingress is loopback-only, and you can only Allow/Deny prompts Claude Code already raised. Run it over Tailscale rather than the public internet.
+
+### How is this different from ntfy notifications?
+ntfy can *tell* you Claude needs you; clawleash lets you *answer* — Allow/Deny right from the phone — without walking back to the desk.
+
+### What happens if my phone is offline?
+After a timeout the permission hook falls back to Claude Code's normal terminal prompt, so your session never gets stuck.
+
+## Roadmap
+
+- Onboarding wizard (one-screen local settings UI: install/connection/QR).
+- Optional **hosted relay** for zero-config access from any network (freemium).
+- Provider-agnostic support beyond Claude Code.
+
+## Claude Code skill
+
+A thin Claude Code skill ([`skill/SKILL.md`](./skill/SKILL.md)) wraps the CLI so you can just ask Claude *"set up phone approval for Claude Code"* and it runs `npx clawleash` and walks you through it.
+
+## Requirements
+
+- Node.js ≥ 18
+- Claude Code with hooks (default in recent versions)
+- For on-the-go access: Tailscale on your Mac and phone
+
+## Contributing
+
+Issues and PRs welcome. Run `npm test` for the unit tests.
+
+## License & trademark
+
+Code: [Apache-2.0](./LICENSE). The **clawleash** name/logo are not covered by the
+code license — see [TRADEMARK.md](./TRADEMARK.md). clawleash is an independent
+community companion for Claude Code and is **not affiliated with Anthropic**;
+"Claude" and "Claude Code" are trademarks of Anthropic, used here descriptively.

package/bin/clawleash.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+"use strict";
+// clawleash — approve/deny Claude Code permission prompts from your phone.
+//
+//   npx clawleash            start the daemon (installs hooks on first run)
+//   npx clawleash url        print the phone URL(s) and exit
+//   npx clawleash uninstall  remove clawleash hooks from ~/.claude/settings.json
+const config = require("../src/config");
+const hooks = require("../src/hooks-install");
+const { startDaemon } = require("../src/daemon");
+const { phoneUrls } = require("../src/netinfo");
+
+function printUrls(cfg) {
+  const urls = phoneUrls(cfg.port, cfg.token);
+  if (!urls.length) {
+    console.log("   No network address found — connect Wi-Fi or start Tailscale.");
+    return;
+  }
+  console.log("   Open on your phone (Tailscale first):");
+  for (const u of urls) console.log(`     ${u.url}${u.tailscale ? "   · Tailscale" : "   · same Wi-Fi only"}`);
+}
+
+function main() {
+  const cmd = process.argv[2] || "start";
+  const cfg = config.ensure();
+
+  if (cmd === "uninstall") {
+    hooks.uninstall();
+    console.log("✔ Removed clawleash hooks from ~/.claude/settings.json");
+    return;
+  }
+  if (cmd === "url") {
+    printUrls(cfg);
+    return;
+  }
+
+  // start
+  if (!hooks.isInstalled(cfg.port)) {
+    hooks.install(cfg.port);
+    console.log("✔ Installed clawleash hooks into ~/.claude/settings.json");
+  }
+  const d = startDaemon({
+    getConfig: () => config.load(),
+    onLog: (m) => console.log("clawleash:", m),
+  });
+  d.listen(cfg.port, () => {
+    const c = config.load();
+    console.log(`\n🦀 clawleash running on 0.0.0.0:${cfg.port}\n`);
+    printUrls(cfg);
+    console.log(`\n   Approvals: ${c.approvals ? "ON" : "off"}   |   ntfy push: ${c.ntfyTopic || "(not set)"}`);
+    console.log("   Scan the URL on your phone and Add to Home Screen.");
+    console.log("   Ctrl-C to stop  ·  `npx clawleash uninstall` to remove hooks.\n");
+  });
+}
+
+main();

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "clawleash",
+  "version": "0.1.0",
+  "description": "Approve or deny Claude Code permission prompts from your phone — so long autonomous runs never stall while you're away from the desk. Self-hosted, token-gated, over Tailscale or LAN.",
+  "keywords": [
+    "claude-code",
+    "claude",
+    "remote-approval",
+    "permission",
+    "hooks",
+    "tailscale",
+    "ntfy",
+    "pwa",
+    "human-in-the-loop",
+    "devtools",
+    "ai-agent",
+    "mobile"
+  ],
+  "homepage": "https://github.com/wilsonwang0713/clawleash#readme",
+  "bugs": "https://github.com/wilsonwang0713/clawleash/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wilsonwang0713/clawleash.git"
+  },
+  "license": "Apache-2.0",
+  "author": "",
+  "type": "commonjs",
+  "bin": {
+    "clawleash": "bin/clawleash.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "skill/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node bin/clawleash.js",
+    "test": "node --test test/*.test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {}
+}

package/skill/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: clawleash
+description: Set up phone approval for Claude Code — let the user approve/deny Claude Code permission prompts and see live agent status from their phone, so long autonomous runs don't stall while they're away. Use when the user asks to control Claude Code remotely, approve prompts from their phone, get mobile notifications when Claude needs permission, or set up clawleash.
+---
+
+# clawleash — phone approval for Claude Code
+
+clawleash is a tiny self-hosted CLI: it installs Claude Code hooks, holds each
+permission prompt open, and serves a token-gated phone page where the user taps
+**Allow / Deny**. The phone reaches the Mac over Tailscale or the same Wi-Fi.
+
+## Steps
+
+1. **Start it** (installs hooks on first run, prints the phone URL):
+   ```
+   npx clawleash
+   ```
+   It runs in the foreground. Tell the user to keep it running (or run it under
+   tmux / a process manager). Re-print the URL anytime with `npx clawleash url`.
+
+2. **Read the printed phone URL(s).** Tailscale (`100.x…`) works on the go; LAN
+   (`192.168.x…`) works on the same Wi-Fi only.
+
+3. **Guide the phone:** open the URL in the phone browser → **Add to Home
+   Screen**. When Claude Code next needs permission while the user is away, the
+   prompt appears on the phone with Allow/Deny buttons.
+
+4. **On the go needs Tailscale:** if there is no `100.x` URL, have the user
+   install Tailscale on both the Mac and the phone, signed into the **same
+   account / same tailnet**. (A fresh personal account does this automatically.)
+
+5. **Optional push:** set an ntfy topic in `~/.config/clawleash/config.json`
+   (`ntfyTopic`) and subscribe to it in the ntfy app for a buzz when a prompt
+   needs them.
+
+To remove: `npx clawleash uninstall` (strips clawleash hooks from
+`~/.claude/settings.json`).
+
+## Notes
+
+- Off by default for outsiders: the page is token-gated (403 without `?k=`),
+  hook ingress is loopback-only, headless sessions are not eligible, and a
+  no-response prompt falls back to the terminal — an offline phone never wedges
+  the session. Prefer Tailscale over exposing the port publicly.

package/src/config.js

@@ -0,0 +1,48 @@
+"use strict";
+// Tiny JSON config under the OS config dir. Holds the secret token, port, and
+// toggles. The token gates the phone-facing routes.
+const os = require("os");
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const DEFAULT_PORT = 4271;
+
+function configDir() {
+  const home = os.homedir();
+  if (process.platform === "win32") {
+    return path.join(process.env.APPDATA || path.join(home, "AppData", "Roaming"), "clawleash");
+  }
+  if (process.platform === "darwin") {
+    return path.join(home, "Library", "Application Support", "clawleash");
+  }
+  return path.join(process.env.XDG_CONFIG_HOME || path.join(home, ".config"), "clawleash");
+}
+
+function configPath() {
+  return path.join(configDir(), "config.json");
+}
+
+function load() {
+  try { return JSON.parse(fs.readFileSync(configPath(), "utf8")); }
+  catch { return {}; }
+}
+
+function save(cfg) {
+  try { fs.mkdirSync(configDir(), { recursive: true }); } catch { /* ignore */ }
+  fs.writeFileSync(configPath(), JSON.stringify(cfg, null, 2));
+}
+
+// Load + fill defaults (generate a token on first run). Idempotent.
+function ensure() {
+  const cfg = load();
+  let changed = false;
+  if (!cfg.token) { cfg.token = crypto.randomBytes(12).toString("hex"); changed = true; }
+  if (!cfg.port) { cfg.port = Number(process.env.CLAWLEASH_PORT) || DEFAULT_PORT; changed = true; }
+  if (typeof cfg.approvals !== "boolean") { cfg.approvals = true; changed = true; }
+  if (typeof cfg.ntfyTopic !== "string") { cfg.ntfyTopic = ""; changed = true; }
+  if (changed) save(cfg);
+  return cfg;
+}
+
+module.exports = { configDir, configPath, load, save, ensure, DEFAULT_PORT };

package/src/daemon.js

@@ -0,0 +1,121 @@
+"use strict";
+// The clawleash daemon: one HTTP server bound to 0.0.0.0.
+//   - /hook/event, /hook/permission   ← Claude Code posts here (LOOPBACK ONLY)
+//   - /, /api/status, /api/permission ← the phone (TOKEN-GATED, any interface)
+//   - /manifest.webmanifest           ← public PWA asset
+const http = require("http");
+const { renderPage, manifestFor } = require("./mobile");
+const { createRegistry } = require("./permissions");
+const { createStatus } = require("./status");
+const { pushNtfy } = require("./notify");
+
+// Settle a held permission well before Claude Code's 600s hook timeout so we
+// can cleanly fall back to the terminal prompt if nobody answers.
+const PERMISSION_TIMEOUT_MS = 9 * 60 * 1000;
+
+function isLoopback(req) {
+  const a = (req.socket && req.socket.remoteAddress) || "";
+  return a === "127.0.0.1" || a === "::1" || a === "::ffff:127.0.0.1";
+}
+
+function readBody(req, cap = 1 << 20) {
+  return new Promise((resolve) => {
+    let data = "";
+    let over = false;
+    req.on("data", (c) => { if (over) return; data += c; if (data.length > cap) over = true; });
+    req.on("end", () => { try { resolve(over ? {} : JSON.parse(data || "{}")); } catch { resolve({}); } });
+    req.on("error", () => resolve({}));
+  });
+}
+
+function startDaemon({ getConfig, onLog } = {}) {
+  const registry = createRegistry();
+  const status = createStatus();
+  const cfg = () => (typeof getConfig === "function" ? getConfig() : {}) || {};
+
+  const server = http.createServer(async (req, res) => {
+    let url;
+    try { url = new URL(req.url, "http://localhost"); } catch { res.writeHead(400); res.end(); return; }
+    const p = url.pathname;
+
+    // ── Hook ingress — loopback only (Claude Code on the same machine) ──
+    if (p === "/hook/event") {
+      if (!isLoopback(req)) { res.writeHead(403); res.end(); return; }
+      const body = await readBody(req);
+      try { status.event(body); } catch { /* ignore */ }
+      res.writeHead(200, { "Content-Type": "application/json" }); res.end("{}");
+      return;
+    }
+    if (p === "/hook/permission") {
+      if (!isLoopback(req)) { res.writeHead(403); res.end(); return; }
+      const body = await readBody(req);
+      const c = cfg();
+      if (!c.approvals) { res.destroy(); return; } // off → Claude Code prompts in the terminal
+      const tool = typeof body.tool_name === "string" ? body.tool_name : "Tool";
+      const input = body.tool_input && typeof body.tool_input === "object" ? body.tool_input : {};
+      const sessionId = body.session_id || "default";
+      const decision = await registry.request(
+        { tool, input, sessionId, project: "" },
+        PERMISSION_TIMEOUT_MS,
+        (pend) => {
+          if (c.ntfyTopic) pushNtfy(c.ntfyTopic, "Permission needed", `${pend.tool}: ${pend.summary}`, { priority: "high", tags: "warning" });
+          if (onLog) onLog(`permission pending — ${pend.tool} (${pend.id})`);
+        }
+      );
+      if (decision.decision === "timeout") { res.destroy(); return; } // fall back to terminal prompt
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "PermissionRequest",
+          decision: {
+            behavior: decision.decision === "allow" ? "allow" : "deny",
+            ...(decision.message ? { message: decision.message } : {}),
+          },
+        },
+      }));
+      return;
+    }
+
+    // ── Token gate for everything phone-facing ──
+    const token = cfg().token || "";
+    if (!token || url.searchParams.get("k") !== token) {
+      res.writeHead(403, { "Content-Type": "text/plain" }); res.end("forbidden");
+      return;
+    }
+    // Token-gated so start_url can carry ?k= (fixes Home Screen 403).
+    if (p === "/manifest.webmanifest") {
+      res.writeHead(200, { "Content-Type": "application/manifest+json; charset=utf-8", "Cache-Control": "no-store" });
+      res.end(manifestFor(token));
+      return;
+    }
+
+    if (p === "/api/status") {
+      const snap = status.snapshot();
+      snap.pending = registry.list();
+      res.writeHead(200, { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" });
+      res.end(JSON.stringify(snap));
+      return;
+    }
+    if (p === "/api/permission" && req.method === "POST") {
+      const id = url.searchParams.get("id") || "";
+      const behavior = url.searchParams.get("decision") === "allow" ? "allow" : "deny";
+      const ok = registry.resolve(id, behavior);
+      res.writeHead(200, { "Content-Type": "application/json" }); res.end(JSON.stringify({ ok }));
+      return;
+    }
+    // default → the mobile page
+    res.writeHead(200, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store" });
+    res.end(renderPage(token));
+  });
+
+  server.on("error", (e) => { if (onLog) onLog("server error: " + (e && e.message)); });
+
+  return {
+    server,
+    registry,
+    status,
+    listen(port, cb) { server.listen(port, "0.0.0.0", cb); return server; },
+  };
+}
+
+module.exports = { startDaemon, PERMISSION_TIMEOUT_MS };

package/src/hooks-install.js

@@ -0,0 +1,77 @@
+"use strict";
+// Idempotently install/remove clawleash's Claude Code hooks in ~/.claude/settings.json.
+// All clawleash hooks are http hooks tagged with ?clawleash=1 so they can be
+// found and removed cleanly without touching the user's other hooks.
+const os = require("os");
+const fs = require("fs");
+const path = require("path");
+
+const MARK = "clawleash=1";
+const STATUS_EVENTS = [
+  "SessionStart", "UserPromptSubmit", "PreToolUse", "PostToolUse",
+  "Stop", "SubagentStart", "SubagentStop", "SessionEnd",
+];
+
+function settingsPath() {
+  return path.join(os.homedir(), ".claude", "settings.json");
+}
+
+function read() {
+  try { return JSON.parse(fs.readFileSync(settingsPath(), "utf8")); }
+  catch { return {}; }
+}
+
+function write(settings) {
+  try { fs.mkdirSync(path.dirname(settingsPath()), { recursive: true }); } catch { /* ignore */ }
+  fs.writeFileSync(settingsPath(), JSON.stringify(settings, null, 2));
+}
+
+function isOurs(entry) {
+  return entry && Array.isArray(entry.hooks) &&
+    entry.hooks.some((h) => h && typeof h.url === "string" && h.url.includes("/hook/") && h.url.includes(MARK));
+}
+
+// Remove every clawleash-tagged hook entry from a settings object (mutates).
+function strip(settings) {
+  const hooks = settings.hooks;
+  if (!hooks || typeof hooks !== "object") return settings;
+  for (const evt of Object.keys(hooks)) {
+    if (!Array.isArray(hooks[evt])) continue;
+    hooks[evt] = hooks[evt].filter((entry) => !isOurs(entry));
+    if (hooks[evt].length === 0) delete hooks[evt];
+  }
+  if (Object.keys(hooks).length === 0) delete settings.hooks;
+  return settings;
+}
+
+function install(port) {
+  const settings = strip(read());
+  settings.hooks = settings.hooks || {};
+  const add = (evt, entry) => { (settings.hooks[evt] = settings.hooks[evt] || []).push(entry); };
+
+  add("PermissionRequest", {
+    matcher: "*",
+    hooks: [{ type: "http", url: `http://127.0.0.1:${port}/hook/permission?${MARK}`, timeout: 600 }],
+  });
+  for (const evt of STATUS_EVENTS) {
+    add(evt, {
+      matcher: "*",
+      hooks: [{ type: "http", url: `http://127.0.0.1:${port}/hook/event?${MARK}`, timeout: 5 }],
+    });
+  }
+  write(settings);
+}
+
+function uninstall() {
+  write(strip(read()));
+}
+
+function isInstalled(port) {
+  const hooks = read().hooks;
+  if (!hooks || !Array.isArray(hooks.PermissionRequest)) return false;
+  return hooks.PermissionRequest.some((entry) =>
+    entry && Array.isArray(entry.hooks) &&
+    entry.hooks.some((h) => h && typeof h.url === "string" && h.url.includes(`:${port}/hook/`) && h.url.includes(MARK)));
+}
+
+module.exports = { install, uninstall, isInstalled, settingsPath };

package/src/mobile.js

@@ -0,0 +1,84 @@
+"use strict";
+// The phone-facing page: a token-gated, installable PWA. Polls /api/status and
+// renders pending allow/deny permission cards + live session bubbles. Tapping a
+// button POSTs to /api/permission.
+
+const FAVICON = "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'%3E%3Ctext y='.9em' font-size='88'%3E%F0%9F%A6%80%3C/text%3E%3C/svg%3E";
+
+function manifestFor(token) {
+  return JSON.stringify({
+    name: "clawleash",
+    short_name: "clawleash",
+    display: "standalone",
+    background_color: "#1c1c1f",
+    theme_color: "#1c1c1f",
+    scope: "/",
+    // Bake the token in: the Home Screen launch uses start_url, NOT the URL you
+    // added — without it the launched PWA would hit a tokenless URL and 403.
+    start_url: "/?k=" + encodeURIComponent(token || ""),
+    icons: [{ src: FAVICON, sizes: "any", type: "image/svg+xml" }],
+  });
+}
+
+function renderPage(token) {
+  return `<!doctype html><html lang="en"><head>
+<meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<title>clawleash</title>
+<link rel="icon" href="${FAVICON}">
+<link rel="apple-touch-icon" href="${FAVICON}">
+<link rel="manifest" href="/manifest.webmanifest?k=${encodeURIComponent(token || "")}">
+<meta name="theme-color" content="#1c1c1f">
+<meta name="apple-mobile-web-app-capable" content="yes">
+<meta name="mobile-web-app-capable" content="yes">
+<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
+<meta name="apple-mobile-web-app-title" content="clawleash">
+<style>
+:root{--bg:#1c1c1f;--card:#232327;--fg:#f4f4f5;--mut:#a1a1aa;--dim:#71717a;--acc:#d97757;--ok:#3fb950;--bad:#f85149;--bd:rgba(255,255,255,.08)}
+@media(prefers-color-scheme:light){:root{--bg:#f5f5f7;--card:#fff;--fg:#18181b;--mut:#6b6b70;--dim:#9b9ba0;--bd:rgba(0,0,0,.08)}}
+*{box-sizing:border-box}body{margin:0;font-family:-apple-system,"Segoe UI",Roboto,sans-serif;background:var(--bg);color:var(--fg);padding:env(safe-area-inset-top) 0 40px}
+header{padding:18px 16px 6px}h1{font-size:18px;margin:0}#sub{font-size:12px;color:var(--mut);margin:4px 0 0}
+.card{background:var(--card);border:1px solid var(--bd);border-radius:14px;margin:12px 16px;padding:14px 16px}
+.card h2{font-size:12px;text-transform:uppercase;letter-spacing:.04em;color:var(--dim);margin:0 0 10px;font-weight:600}
+.row{display:flex;justify-content:space-between;align-items:center;padding:7px 0;border-top:1px solid var(--bd);font-size:14px}
+.row:first-of-type{border-top:none}.run .dot{display:inline-block;width:8px;height:8px;border-radius:50%;background:var(--acc);margin-right:8px;animation:p 1s infinite}
+@keyframes p{0%,100%{opacity:1}50%{opacity:.3}}.muted{color:var(--mut)}.none{color:var(--dim);font-size:14px;padding:6px 0}
+#ts{font-size:11px;color:var(--dim);text-align:center;margin-top:16px}
+.bub{display:flex;align-items:flex-start;gap:8px;margin:12px 0}.bub:first-child{margin-top:0}
+.crab{font-size:24px;line-height:1.1;flex:none}
+.say{position:relative;background:var(--bg);border:1px solid var(--bd);border-radius:14px;padding:9px 12px;flex:1;min-width:0}
+.say:before{content:"";position:absolute;left:-7px;top:13px;border:6px solid transparent;border-right-color:var(--bd);border-left:0}
+.ttl{font-size:14px;font-weight:600;word-break:break-word}.subl{font-size:12px;color:var(--mut);margin-top:2px;word-break:break-word}
+.st{font-size:10px;font-weight:700;text-transform:uppercase;padding:1px 6px;border-radius:6px;margin-left:6px}
+.s-working,.s-thinking{background:rgba(217,119,87,.18);color:var(--acc)}.s-idle{background:var(--bd);color:var(--dim)}
+.perm{border-color:var(--acc)}.ptool{font-size:11px;color:var(--acc);font-weight:700;text-transform:uppercase;letter-spacing:.04em}
+.psum{font-size:14px;margin:5px 0 11px;word-break:break-word;font-family:ui-monospace,Menlo,monospace}
+.pbtns{display:flex;gap:8px}.pbtns button{flex:1;border:0;border-radius:10px;padding:12px;font-size:15px;font-weight:600;color:#fff}
+.allow{background:var(--ok)}.deny{background:var(--bad)}.pbtns button:active{opacity:.65}
+</style></head><body>
+<header><h1>🦀 clawleash</h1><p id="sub">connecting…</p></header>
+<div id="perms"></div>
+<div class="card"><h2>Sessions</h2><div id="sessions"><div class="none">—</div></div></div>
+<div class="card"><h2>Running now</h2><div id="running"><div class="none">—</div></div></div>
+<div id="ts"></div>
+<script>
+var K=${JSON.stringify(token || "")};
+function esc(s){var d=document.createElement('div');d.textContent=s==null?'':s;return d.innerHTML}
+function decide(id,d){fetch('/api/permission?k='+encodeURIComponent(K)+'&id='+encodeURIComponent(id)+'&decision='+d,{method:'POST'}).then(function(){tick()}).catch(function(){});}
+document.getElementById('perms').addEventListener('click',function(e){var b=e.target.closest&&e.target.closest('button[data-id]');if(!b)return;b.disabled=true;decide(b.getAttribute('data-id'),b.getAttribute('data-d'));});
+function renderPerms(list){var el=document.getElementById('perms');if(!list||!list.length){el.innerHTML='';return}
+ el.innerHTML=list.map(function(p){return '<div class="card perm"><div class="ptool">'+esc(p.tool)+(p.project?' · '+esc(p.project):'')+'</div><div class="psum">'+esc(p.summary)+'</div><div class="pbtns"><button class="allow" data-id="'+esc(p.id)+'" data-d="allow">Allow</button><button class="deny" data-id="'+esc(p.id)+'" data-d="deny">Deny</button></div></div>';}).join('');}
+function renderSessions(list){var el=document.getElementById('sessions');if(!list||!list.length){el.innerHTML='<div class="none">no live sessions</div>';return}
+ el.innerHTML=list.map(function(s){var st=s.state||'idle';var sub=(s.agents&&s.agents.length)?s.agents.join(', '):st;
+  return '<div class="bub"><div class="crab">🦀</div><div class="say"><div class="ttl">'+esc(s.project||'session')+'<span class="st s-'+esc(st)+'">'+esc(st)+'</span></div><div class="subl">'+esc(sub)+'</div></div></div>';}).join('');}
+function tick(){fetch('/api/status?k='+encodeURIComponent(K)).then(function(r){return r.json()}).then(function(d){
+  var run=d.running||[];var p=d.pending||[];
+  document.getElementById('sub').textContent=(d.liveSessions||0)+' live session'+(d.liveSessions===1?'':'s')+(p.length?' · '+p.length+' awaiting you':'');
+  renderPerms(p);renderSessions(d.sessions);
+  document.getElementById('running').innerHTML=run.length?run.map(function(x){return '<div class="row run"><span><span class="dot"></span>'+esc(x.type)+'</span><span class="muted">'+(x.count>1?'×'+x.count:'running')+'</span></div>'}).join(''):'<div class="none">nothing running</div>';
+  document.getElementById('ts').textContent='updated '+new Date().toLocaleTimeString();
+ }).catch(function(){document.getElementById('sub').textContent='disconnected — is your Mac awake?'});}
+tick();setInterval(tick,5000);
+</script></body></html>`;
+}
+
+module.exports = { renderPage, manifestFor };

package/src/netinfo.js

@@ -0,0 +1,29 @@
+"use strict";
+// Local network introspection: enumerate reachable IPs and build phone URLs,
+// Tailscale (100.64.0.0/10) first, then LAN.
+const os = require("os");
+
+function isTailscaleIp(ip) {
+  const m = /^100\.(\d+)\./.exec(ip || "");
+  return !!m && +m[1] >= 64 && +m[1] <= 127;
+}
+
+function phoneUrls(port, token) {
+  const ifs = os.networkInterfaces() || {};
+  const out = [];
+  for (const name of Object.keys(ifs)) {
+    for (const ni of ifs[name] || []) {
+      if (ni.family !== "IPv4" || ni.internal) continue;
+      const tailscale = isTailscaleIp(ni.address);
+      out.push({
+        ip: ni.address,
+        tailscale,
+        kind: tailscale ? "tailscale" : "lan",
+        url: `http://${ni.address}:${port}/?k=${token}`,
+      });
+    }
+  }
+  return out.sort((a, b) => (b.tailscale ? 1 : 0) - (a.tailscale ? 1 : 0));
+}
+
+module.exports = { isTailscaleIp, phoneUrls };

package/src/notify.js

@@ -0,0 +1,30 @@
+"use strict";
+// Push a short notification to a phone via ntfy.sh (free, open-source).
+// The user installs the ntfy app and subscribes to their topic; we POST to it.
+const https = require("https");
+
+function pushNtfy(topic, title, message, opts = {}) {
+  if (!topic || typeof topic !== "string") return;
+  try {
+    const body = Buffer.from(String(message == null ? "" : message), "utf8");
+    // Title header must be ASCII; keep details in the (UTF-8) body.
+    const asciiTitle = String(title || "clawleash").replace(/[^\x20-\x7E]/g, "").slice(0, 80) || "clawleash";
+    const headers = {
+      "Content-Type": "text/plain; charset=utf-8",
+      "Content-Length": body.length,
+      "Title": asciiTitle,
+    };
+    if (opts.tags) headers.Tags = String(opts.tags);
+    if (opts.priority) headers.Priority = String(opts.priority);
+    const req = https.request(
+      { hostname: "ntfy.sh", path: "/" + encodeURIComponent(topic), method: "POST", headers, timeout: 4000 },
+      (res) => { res.resume(); }
+    );
+    req.on("error", () => {});
+    req.on("timeout", () => { try { req.destroy(); } catch {} });
+    req.write(body);
+    req.end();
+  } catch { /* best-effort */ }
+}
+
+module.exports = { pushNtfy };

package/src/permissions.js

@@ -0,0 +1,70 @@
+"use strict";
+// Pending permission registry. A PermissionRequest hook holds its HTTP request
+// open; we park a resolver here and settle it when the phone (or a timeout)
+// answers. The phone calls resolve(id, "allow"|"deny"); a timeout settles as
+// "timeout" so the caller can let Claude Code fall back to its terminal prompt.
+const path = require("path");
+
+function summarize(tool, input) {
+  const ti = input && typeof input === "object" ? input : {};
+  const trim = (s, n) => {
+    const t = String(s == null ? "" : s).replace(/\s+/g, " ").trim();
+    return t.length > n ? `${t.slice(0, n - 1)}…` : t;
+  };
+  if (tool === "Bash") return trim(ti.command, 90) || "Bash command";
+  if (tool === "Write" || tool === "Edit" || tool === "MultiEdit" || tool === "NotebookEdit") {
+    const f = ti.file_path || ti.notebook_path || "";
+    return f ? `${tool} ${path.basename(String(f))}` : tool;
+  }
+  if (tool === "WebFetch") return trim(ti.url, 90) || "WebFetch";
+  if (tool === "Read" && ti.file_path) return `Read ${path.basename(String(ti.file_path))}`;
+  return tool || "Tool";
+}
+
+function createRegistry() {
+  const pending = new Map(); // id -> { resolve, timer, tool, input, sessionId, project, createdAt }
+  let counter = 0;
+
+  function request({ tool, input, sessionId, project }, timeoutMs, onPending) {
+    return new Promise((resolve) => {
+      const id = `p${++counter}`;
+      const timer = setTimeout(() => {
+        if (pending.delete(id)) resolve({ decision: "timeout" });
+      }, timeoutMs);
+      pending.set(id, { resolve, timer, tool, input, sessionId, project, createdAt: Date.now() });
+      if (onPending) {
+        try { onPending({ id, tool, summary: summarize(tool, input), project: project || "", sessionId: sessionId || "" }); }
+        catch { /* best-effort */ }
+      }
+    });
+  }
+
+  function list() {
+    return [...pending.entries()].map(([id, p]) => ({
+      id,
+      tool: p.tool,
+      summary: summarize(p.tool, p.input),
+      project: p.project || "",
+      sessionId: p.sessionId || "",
+      createdAt: p.createdAt,
+    }));
+  }
+
+  function resolve(id, decision) {
+    const p = pending.get(id);
+    if (!p) return false;
+    clearTimeout(p.timer);
+    pending.delete(id);
+    p.resolve({
+      decision: decision === "allow" ? "allow" : "deny",
+      message: decision === "allow" ? undefined : "Denied from phone",
+    });
+    return true;
+  }
+
+  function size() { return pending.size; }
+
+  return { request, list, resolve, size };
+}
+
+module.exports = { createRegistry, summarize };

package/src/status.js

@@ -0,0 +1,74 @@
+"use strict";
+// In-memory live status fed by Claude Code hook events. Tracks per-session state
+// and running subagents so the phone page can show "what's happening now".
+const path = require("path");
+
+const STATE_BY_EVENT = {
+  SessionStart: "idle",
+  UserPromptSubmit: "thinking",
+  PreToolUse: "working",
+  PostToolUse: "working",
+  Stop: "idle",
+  SubagentStart: "working",
+  SubagentStop: "working",
+};
+
+function createStatus() {
+  const sessions = new Map();   // sessionId -> { project, state, headless, updatedAt }
+  const subagents = new Map();  // toolUseId -> { type, sessionId }
+
+  function event(e) {
+    const evt = e.event || e.hook_event_name || "";
+    const sid = e.session_id || "default";
+
+    if (evt === "SessionEnd") {
+      sessions.delete(sid);
+      for (const [k, v] of subagents) if (v.sessionId === sid) subagents.delete(k);
+      return;
+    }
+
+    const s = sessions.get(sid) || { project: "", state: "idle", headless: false, updatedAt: 0 };
+    if (e.cwd) s.project = path.basename(String(e.cwd));
+    if (e.headless) s.headless = true;
+    if (STATE_BY_EVENT[evt]) s.state = STATE_BY_EVENT[evt];
+    s.updatedAt = Date.now();
+    sessions.set(sid, s);
+
+    const subType =
+      (e.tool_input && typeof e.tool_input.subagent_type === "string" && e.tool_input.subagent_type) ||
+      (typeof e.agent_type === "string" && e.agent_type) || "";
+    if (subType && e.tool_use_id && (evt === "PreToolUse" || evt === "SubagentStart")) {
+      subagents.set(e.tool_use_id, { type: subType, sessionId: sid });
+    }
+    if (e.tool_use_id && (evt === "PostToolUse" || evt === "SubagentStop")) {
+      subagents.delete(e.tool_use_id);
+    }
+  }
+
+  function snapshot() {
+    const running = {};
+    const agentsBySession = new Map();
+    for (const [, v] of subagents) {
+      if (!v.type) continue;
+      running[v.type] = (running[v.type] || 0) + 1;
+      const a = agentsBySession.get(v.sessionId) || [];
+      a.push(v.type);
+      agentsBySession.set(v.sessionId, a);
+    }
+    const sess = [];
+    for (const [id, s] of sessions) {
+      if (s.headless) continue;
+      sess.push({ id, project: s.project, state: s.state, agents: agentsBySession.get(id) || [], updatedAt: s.updatedAt });
+    }
+    sess.sort((a, b) => b.updatedAt - a.updatedAt);
+    return {
+      running: Object.entries(running).map(([type, count]) => ({ type, count })),
+      sessions: sess,
+      liveSessions: sess.length,
+    };
+  }
+
+  return { event, snapshot };
+}
+
+module.exports = { createStatus };