bund 0.1.0__py3-none-any.whl

bund/__init__.py

@@ -0,0 +1,3 @@
+"""bund — Telegram pings for coding agents. Approve from your phone."""
+
+__version__ = "0.1.0"

bund/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

bund/ask.py

@@ -0,0 +1,35 @@
+import html
+import secrets
+import sys
+
+from . import config, hook, templates
+from .telegram import TelegramError, send
+
+
+def ask(question: str, timeout: int = None) -> int:
+    """Universal protocol: prints allow|deny|timeout, exit 0/1/2."""
+    cfg = config.load()
+    if not config.ready(cfg):
+        print("bund is not configured. Run: bund set --token <token> && bund set --chat auto",
+              file=sys.stderr)
+        print("timeout", flush=True)
+        return 2
+    request_id = secrets.token_hex(6)
+    text = f"{templates.say('permission', {'tool': 'a question', 'command': question})}\n\n<pre>{html.escape(question)}</pre>"
+    rows = [[("✅ Approve", f"{request_id}:a"), ("❌ Deny", f"{request_id}:d")]]
+    try:
+        send(text, rows, cfg=cfg)
+    except TelegramError as e:
+        print(f"Telegram error: {e}", file=sys.stderr)
+        print("timeout", flush=True)
+        return 2
+    dec = hook.wait_for(request_id, cfg, timeout or config.timeout_sec(cfg))
+    action = (dec or {}).get("action")
+    if action in ("approve", "approve_all"):
+        print("allow", flush=True)
+        return 0
+    if action == "deny":
+        print("deny", flush=True)
+        return 1
+    print("timeout", flush=True)
+    return 2

bund/cli.py

@@ -0,0 +1,118 @@
+import argparse
+import sys
+
+from . import __version__, config
+
+
+def main(argv=None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="bund",
+        description="Telegram pings for coding agents. Approve from your phone.",
+    )
+    parser.add_argument("-m", "--message", metavar="TEXT", help="send a Telegram message")
+    parser.add_argument("--version", action="version", version=f"bund {__version__}")
+    sub = parser.add_subparsers(dest="cmd")
+
+    p_set = sub.add_parser("set", help="configure token, chat, or tone")
+    group = p_set.add_mutually_exclusive_group(required=True)
+    group.add_argument("--token", metavar="BOT_TOKEN", help="Telegram bot token from @BotFather")
+    group.add_argument("--chat", metavar="ID|auto", help="chat id, or 'auto' to pick yourself")
+    group.add_argument("--tone", choices=["sarcasm", "plain"], help="message tone")
+
+    sub.add_parser("install", help="add bund hooks to ~/.claude/settings.json")
+    sub.add_parser("uninstall", help="remove only bund's hooks")
+    sub.add_parser("test", help="send a test message to your chat")
+
+    p_ask = sub.add_parser("ask", help="ask a question over Telegram; prints allow|deny|timeout")
+    p_ask.add_argument("question", nargs="*", help="the question to ask")
+    p_ask.add_argument("--timeout", type=int, default=None, help="seconds to wait (default 600)")
+
+    sub.add_parser("hook", help="internal: called by agent hooks, reads JSON from stdin")
+
+    args = parser.parse_args(argv)
+
+    if args.message:
+        sys.exit(_send_message(args.message))
+
+    if args.cmd == "set":
+        sys.exit(_cmd_set(args))
+    if args.cmd == "install":
+        from . import install as install_mod
+        sys.exit(install_mod.install())
+    if args.cmd == "uninstall":
+        from . import install as install_mod
+        sys.exit(install_mod.uninstall())
+    if args.cmd == "test":
+        sys.exit(_cmd_test())
+    if args.cmd == "ask":
+        from . import ask as ask_mod
+        question = " ".join(args.question).strip()
+        if not question and not sys.stdin.isatty():
+            question = sys.stdin.read().strip()
+        if not question:
+            print("Give a question: bund ask \"deploy to prod?\"", file=sys.stderr)
+            sys.exit(2)
+        sys.exit(ask_mod.ask(question, args.timeout))
+    if args.cmd == "hook":
+        from . import hook as hook_mod
+        hook_mod.main()
+
+    parser.print_help()
+
+
+def _cmd_set(args) -> int:
+    from . import setup_chat
+
+    cfg = config.load()
+    if args.token is not None:
+        return setup_chat.set_token(cfg, args.token)
+    if args.chat is not None:
+        if args.chat.strip().lower() == "auto":
+            return setup_chat.set_chat_auto(cfg)
+        return setup_chat.set_chat_id(cfg, args.chat)
+    if args.tone:
+        cfg["tone"] = args.tone
+        config.save(cfg)
+        from . import templates
+        print(f"Tone set to {args.tone}. Sample:")
+        print("  " + templates.say("permission", {"tool": "Bash", "project": "my-project"}))
+        return 0
+    return 1
+
+
+def _cmd_test() -> int:
+    from .telegram import TelegramError, send
+
+    cfg = config.load()
+    if not config.ready(cfg):
+        print("Not configured yet. Run: bund set --token <token> && bund set --chat auto")
+        return 1
+    try:
+        from . import templates
+
+        send(templates.say("test", {}), cfg=cfg)
+    except TelegramError as e:
+        print(f"Telegram error: {e}")
+        return 1
+    print(f"Test message sent to chat {cfg['chatId']}.")
+    return 0
+
+
+def _send_message(text: str) -> int:
+    from .telegram import TelegramError, send
+
+    cfg = config.load()
+    if not config.ready(cfg):
+        print("Not configured yet. Run: bund set --token <token> && bund set --chat auto")
+        return 1
+    try:
+        send(text, cfg=cfg)
+    except TelegramError as e:
+        print(f"Telegram error: {e}")
+        return 1
+    print("Sent.")
+    return 0
+
+
+if __name__ == "__main__":
+    main()

bund/config.py

@@ -0,0 +1,51 @@
+import json
+import os
+import stat
+from pathlib import Path
+
+DEFAULT_TIMEOUT_SEC = 600
+
+
+def config_dir() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME") or os.path.join(str(Path.home()), ".config")
+    return Path(base) / "bund"
+
+
+def config_path() -> Path:
+    return config_dir() / "config.json"
+
+
+def load() -> dict:
+    try:
+        with open(config_path(), encoding="utf-8") as f:
+            data = json.load(f)
+        return data if isinstance(data, dict) else {}
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return {}
+
+
+def save(cfg: dict) -> dict:
+    d = config_dir()
+    d.mkdir(parents=True, exist_ok=True)
+    p = config_path()
+    tmp = p.with_name("config.json.tmp")
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(cfg, f, indent=2)
+        f.write("\n")
+    os.replace(tmp, p)
+    try:
+        os.chmod(p, stat.S_IRUSR | stat.S_IWUSR)
+    except OSError:
+        pass
+    return cfg
+
+
+def ready(cfg: dict) -> bool:
+    return bool(cfg.get("token") and cfg.get("chatId"))
+
+
+def timeout_sec(cfg: dict) -> int:
+    try:
+        return int(cfg.get("timeoutSec") or DEFAULT_TIMEOUT_SEC)
+    except (TypeError, ValueError):
+        return DEFAULT_TIMEOUT_SEC

bund/hook.py

@@ -0,0 +1,189 @@
+import html
+import json
+import os
+import secrets
+import sys
+import time
+
+from . import config, poller, rules, templates
+from .telegram import TelegramError, edit, send
+
+MAX_CMD_CHARS = 3500
+
+
+def main() -> None:
+    try:
+        _run()
+    except Exception:
+        pass  # universal fallback: silent exit 0 -> terminal prompt
+    sys.exit(0)
+
+
+def _run() -> None:
+    raw = sys.stdin.read()
+    try:
+        event = json.loads(raw)
+    except (json.JSONDecodeError, ValueError):
+        return
+    if not isinstance(event, dict):
+        return
+    name = event.get("hook_event_name")
+    if name == "PermissionRequest":
+        permission(event)
+    elif name == "Stop":
+        stop(event)
+
+
+def _truncate(text: str) -> str:
+    if len(text) <= MAX_CMD_CHARS:
+        return text
+    return text[:MAX_CMD_CHARS] + "\n… (truncated, deny if you can't read it all)"
+
+
+def _display(event: dict) -> str:
+    tool = event.get("tool_name") or "?"
+    tool_input = event.get("tool_input")
+    return _truncate(rules.command_text(tool, tool_input))
+
+
+def build_decision(action: str, tool_name: str = None, rule=None) -> dict:
+    """Claude Code PermissionRequest output. Shared with tests."""
+    decision = {}
+    if action == "approve":
+        decision["behavior"] = "allow"
+    elif action == "approve_all":
+        decision["behavior"] = "allow"
+        entry = {"type": "addRules", "behavior": "allow", "destination": "localSettings"}
+        if rule:
+            tool, pattern = rule
+            r = {"toolName": tool}
+            if pattern:
+                r["ruleContent"] = pattern
+            entry["rules"] = [r]
+        else:
+            entry["rules"] = [{"toolName": tool_name or "?"}]
+        decision["updatedPermissions"] = [entry]
+    else:  # deny
+        decision["behavior"] = "deny"
+        decision["message"] = "Denied from phone"
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": "PermissionRequest",
+            "decision": decision,
+        }
+    }
+
+
+def wait_for(request_id: str, cfg: dict, timeout: int):
+    """Watch decision file; poll Telegram when holding the lock. Returns dict or None."""
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        dec = poller.read_decision(request_id)
+        if dec:
+            poller.drop_decision(request_id)
+            return dec
+        if poller.try_acquire():
+            try:
+                remaining = deadline - time.time()
+                if remaining > 1:
+                    poller.poll_round(cfg, max_wait=min(poller.POLL_TIMEOUT, int(remaining)))
+            except Exception:
+                pass
+            finally:
+                poller.release()
+        else:
+            time.sleep(0.5)
+    dec = poller.read_decision(request_id)
+    if dec:
+        poller.drop_decision(request_id)
+        return dec
+    return None
+
+
+def permission(event: dict) -> None:
+    cfg = config.load()
+    if not config.ready(cfg):
+        return
+    tool = event.get("tool_name") or "?"
+    tool_input = event.get("tool_input")
+    project = os.path.basename(str(event.get("cwd") or ".")) or "."
+    display = _display(event)
+    dangerous = rules.is_dangerous(tool, tool_input)
+    rule = None if dangerous else rules.rule_for(tool, tool_input)
+
+    request_id = secrets.token_hex(6)
+    lines = [
+        templates.say(
+            "permission", {"tool": tool, "command": display, "project": project}
+        )
+    ]
+    if dangerous:
+        lines.append(templates.say("dangerous", {}))
+    lines.append(f"<pre>{html.escape(display)}</pre>")
+    text = "\n\n".join(lines)
+
+    rows = [[("✅ Approve", f"{request_id}:a"), ("❌ Deny", f"{request_id}:d")]]
+    if rule:
+        label = f"♾ Approve all similar: {rule[0]}({rule[1]})" if rule[1] else f"♾ Approve all similar: {rule[0]}"
+        rows.append([(label, f"{request_id}:s")])
+
+    try:
+        msg = send(text, rows, cfg=cfg)
+    except TelegramError:
+        return
+    message_id = msg.get("message_id")
+    chat_id = msg.get("chat", {}).get("id", cfg.get("chatId"))
+
+    timeout = config.timeout_sec(cfg)
+    dec = wait_for(request_id, cfg, timeout)
+
+    if dec is None:
+        _outcome(chat_id, message_id, templates.say("timeout", {}), cfg)
+        return
+
+    action = dec.get("action", "deny")
+    outcome_line = templates.say(
+        {"approve": "approved", "deny": "denied", "approve_all": "approve_all"}.get(
+            action, "denied"
+        ),
+        {},
+    )
+    _outcome(chat_id, message_id, outcome_line, cfg)
+    print(
+        json.dumps(build_decision(action, tool, rule)),
+        flush=True,
+    )
+
+
+def _outcome(chat_id, message_id: int, line: str, cfg: dict) -> None:
+    try:
+        edit(chat_id, message_id, line, None, cfg=cfg)
+    except TelegramError:
+        pass
+
+
+def stop(event: dict) -> None:
+    cfg = config.load()
+    if not config.ready(cfg):
+        return
+    session = str(event.get("session_id") or "")
+    project = os.path.basename(str(event.get("cwd") or ".")) or "."
+    state = poller.load_state()
+    last = state.setdefault("lastStop", {})
+    now = time.time()
+    if session and session in last:
+        try:
+            if now - float(last[session]) < 20:
+                return
+        except (TypeError, ValueError):
+            pass
+    if session:
+        last[session] = now
+        if len(last) > 50:
+            for key in [k for k, v in last.items() if isinstance(v, (int, float)) and now - v > 3600]:
+                last.pop(key, None)
+        poller.save_state(state)
+    send(
+        templates.say("done", {"project": project, "time": time.strftime("%H:%M")}),
+        cfg=cfg,
+    )

bund/install.py

@@ -0,0 +1,125 @@
+import json
+import shutil
+import sys
+from pathlib import Path
+
+SETTINGS = Path.home() / ".claude" / "settings.json"
+BACKUP = Path(str(SETTINGS) + ".bund-backup")
+
+HOOK_TIMEOUT = 900
+EVENTS = ("PermissionRequest", "Stop")
+
+
+def _entry() -> dict:
+    return {
+        "type": "command",
+        "command": sys.executable,
+        "args": ["-m", "bund", "hook"],
+        "timeout": HOOK_TIMEOUT,
+        "statusMessage": "waiting for your phone…",
+    }
+
+
+def is_bund_handler(handler) -> bool:
+    if not isinstance(handler, dict):
+        return False
+    joined = (str(handler.get("command", "")) + " " + " ".join(
+        str(a) for a in (handler.get("args") or [])
+    )).lower()
+    return "bund" in joined and "hook" in joined
+
+
+def _read() -> dict:
+    if not SETTINGS.exists():
+        return {}
+    try:
+        with open(SETTINGS, encoding="utf-8") as f:
+            data = json.load(f)
+    except (json.JSONDecodeError, OSError):
+        print(f"ERROR: {SETTINGS} is not valid JSON. Fix it first; bund won't overwrite it.")
+        raise SystemExit(1)
+    if not isinstance(data, dict):
+        raise SystemExit(f"ERROR: {SETTINGS} has unexpected content. Not touching it.")
+    if not BACKUP.exists():
+        shutil.copy2(SETTINGS, BACKUP)
+        print(f"Backed up existing settings to {BACKUP.name}")
+    return data
+
+
+def _write(settings: dict) -> None:
+    SETTINGS.parent.mkdir(parents=True, exist_ok=True)
+    tmp = SETTINGS.with_name("settings.json.tmp")
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(settings, f, indent=2)
+        f.write("\n")
+    shutil.move(str(tmp), str(SETTINGS))
+
+
+def install() -> int:
+    settings = _read()
+    hooks = settings.setdefault("hooks", {})
+    if not isinstance(hooks, dict):
+        print(f"ERROR: {SETTINGS} has a 'hooks' value of the wrong type. Not touching it.")
+        return 1
+    added = 0
+    for event in EVENTS:
+        groups = hooks.setdefault(event, [])
+        if not isinstance(groups, list):
+            continue
+        if any(
+            is_bund_handler(h)
+            for g in groups
+            if isinstance(g, dict)
+            for h in (g.get("hooks") or [])
+        ):
+            continue
+        groups.append({"hooks": [_entry()]})
+        added += 1
+    if not added:
+        print("bund hooks are already installed.")
+        return 0
+    _write(settings)
+    print(f"Installed {added} hook(s) into {SETTINGS}")
+    print("Claude Code will now ping your phone for permissions.")
+    return 0
+
+
+def uninstall() -> int:
+    if not SETTINGS.exists():
+        print("Nothing to remove (no settings file).")
+        return 0
+    settings = _read()
+    hooks = settings.get("hooks")
+    if not isinstance(hooks, dict):
+        print("Nothing to remove.")
+        return 0
+    removed = 0
+    for event in list(hooks.keys()):
+        groups = hooks.get(event)
+        if not isinstance(groups, list):
+            continue
+        kept_groups = []
+        for g in groups:
+            if not isinstance(g, dict):
+                kept_groups.append(g)
+                continue
+            handlers = g.get("hooks") or []
+            kept = [h for h in handlers if not is_bund_handler(h)]
+            removed += len(handlers) - len(kept)
+            if kept:
+                g["hooks"] = kept
+                kept_groups.append(g)
+            elif not handlers:
+                kept_groups.append(g)
+        if kept_groups:
+            hooks[event] = kept_groups
+        else:
+            hooks.pop(event, None)
+    if not hooks:
+        settings.pop("hooks", None)
+    _write(settings)
+    if removed:
+        print(f"Removed {removed} bund hook(s). Everything else was left alone.")
+    else:
+        print("No bund hooks found.")
+    return 0

bund/poller.py

@@ -0,0 +1,171 @@
+import json
+import os
+import shutil
+import time
+from pathlib import Path
+
+from . import config
+from .telegram import TelegramError, answer, call
+
+LOCK_STALE_SEC = 60
+DECISION_TTL_SEC = 3600
+POLL_TIMEOUT = 25
+
+
+def _state_path() -> Path:
+    return config.config_dir() / "state.json"
+
+
+def load_state() -> dict:
+    try:
+        with open(_state_path(), encoding="utf-8") as f:
+            data = json.load(f)
+        return data if isinstance(data, dict) else {}
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return {}
+
+
+def save_state(state: dict) -> None:
+    d = config.config_dir()
+    d.mkdir(parents=True, exist_ok=True)
+    p = _state_path()
+    tmp = p.with_name("state.json.tmp")
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(state, f)
+    os.replace(tmp, p)
+
+
+def decisions_dir() -> Path:
+    d = config.config_dir() / "decisions"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def lock_dir() -> Path:
+    return config.config_dir() / "poller.lock"
+
+
+def try_acquire() -> bool:
+    config.config_dir().mkdir(parents=True, exist_ok=True)
+    ld = lock_dir()
+    for _ in range(2):
+        try:
+            ld.mkdir()
+            _touch_heartbeat(ld)
+            return True
+        except FileExistsError:
+            if _is_stale(ld):
+                shutil.rmtree(ld, ignore_errors=True)
+                continue
+            return False
+    return False
+
+
+def _is_stale(ld: Path) -> bool:
+    try:
+        return (time.time() - (ld / "heartbeat").stat().st_mtime) > LOCK_STALE_SEC
+    except OSError:
+        try:
+            return (time.time() - ld.stat().st_mtime) > LOCK_STALE_SEC
+        except OSError:
+            return True
+
+
+def _touch_heartbeat(ld: Path = None) -> None:
+    try:
+        hb = (ld or lock_dir()) / "heartbeat"
+        hb.write_text(str(time.time()), encoding="utf-8")
+    except OSError:
+        pass
+
+
+def release() -> None:
+    shutil.rmtree(lock_dir(), ignore_errors=True)
+
+
+def read_decision(request_id: str):
+    p = decisions_dir() / f"{request_id}.json"
+    try:
+        with open(p, encoding="utf-8") as f:
+            data = json.load(f)
+        return data if isinstance(data, dict) else None
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return None
+
+
+def drop_decision(request_id: str) -> None:
+    try:
+        (decisions_dir() / f"{request_id}.json").unlink()
+    except OSError:
+        pass
+
+
+def write_decision(request_id: str, action: str) -> bool:
+    p = decisions_dir() / f"{request_id}.json"
+    if p.exists():
+        return False
+    tmp = p.with_name(f".{request_id}.{os.getpid()}.tmp")
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump({"id": request_id, "action": action, "at": time.time()}, f)
+    os.replace(tmp, p)
+    return True
+
+
+def cleanup_decisions() -> None:
+    now = time.time()
+    try:
+        for p in decisions_dir().glob("*.json"):
+            try:
+                if now - p.stat().st_mtime > DECISION_TTL_SEC:
+                    p.unlink()
+            except OSError:
+                pass
+    except OSError:
+        pass
+
+
+_ACTIONS = {"a": "approve", "d": "deny", "s": "approve_all"}
+
+
+def _handle_callback(cq: dict, cfg: dict) -> None:
+    from_id = (cq.get("from") or {}).get("id")
+    chat_id = ((cq.get("message") or {}).get("chat") or {}).get("id")
+    owner = str(cfg.get("chatId"))
+    if str(from_id) != owner and str(chat_id) != owner:
+        return
+    data = cq.get("callback_data") or ""
+    try:
+        request_id, code = data.split(":", 1)
+    except ValueError:
+        return
+    action = _ACTIONS.get(code)
+    if not action or not request_id:
+        return
+    created = write_decision(request_id, action)
+    try:
+        answer(cq.get("id", ""), "Already handled" if not created else "Got it", cfg=cfg)
+    except TelegramError:
+        pass
+
+
+def poll_round(cfg: dict, max_wait: int = POLL_TIMEOUT) -> int:
+    """One getUpdates round. Writes decision files for ALL waiting requests."""
+    cleanup_decisions()
+    state = load_state()
+    offset = int(state.get("updateOffset") or 0)
+    updates = call(
+        cfg.get("token"),
+        "getUpdates",
+        {"offset": offset, "timeout": max_wait, "allowed_updates": ["callback_query"]},
+        timeout=max_wait + 10,
+    )
+    for upd in updates or []:
+        try:
+            state["updateOffset"] = int(upd["update_id"]) + 1
+        except (KeyError, TypeError, ValueError):
+            continue
+        cq = upd.get("callback_query")
+        if isinstance(cq, dict):
+            _handle_callback(cq, cfg)
+    save_state(state)
+    return len(updates or [])

bund/rules.py

@@ -0,0 +1,54 @@
+import json
+import re
+
+DANGER_PATTERNS = [
+    r"\brm\s+-\w*[rR]\w*[fF]\b",
+    r"\brm\s+-\w*[fF]\w*[rR]\b",
+    r"\bsudo\b",
+    r"git\s+push\b.*(\s-f\b|--force\b)",
+    r"(curl|wget)\b[^|]*\|\s*(sudo\s+)?(ba|z|da|fi)?sh\b",
+    r"\bchmod\s+-[a-zA-Z]*[rR]",
+    r"\bDROP\s+TABLE\b",
+    r"\bmkfs(\.\w+)?\b",
+    r"\bdd\s+if=",
+]
+
+_COMPLEX = re.compile(r"&&|;|\||\$\(|`")
+
+_FILE_TOOLS = {"Edit", "Write", "MultiEdit", "NotebookEdit", "Read"}
+
+
+def command_text(tool_name: str, tool_input) -> str:
+    if isinstance(tool_input, dict):
+        cmd = tool_input.get("command")
+        if isinstance(cmd, str) and cmd:
+            return cmd
+        for key in ("file_path", "path", "pattern", "plan"):
+            val = tool_input.get(key)
+            if isinstance(val, str) and val:
+                return val
+        try:
+            return json.dumps(tool_input, ensure_ascii=False)
+        except (TypeError, ValueError):
+            return str(tool_input)
+    return str(tool_input)
+
+
+def is_dangerous(tool_name: str, tool_input) -> bool:
+    text = command_text(tool_name, tool_input)
+    return any(re.search(p, text, re.IGNORECASE) for p in DANGER_PATTERNS)
+
+
+def rule_for(tool_name: str, tool_input):
+    """Return (toolName, ruleContent|None) for 'approve all similar', or None."""
+    if not tool_name:
+        return None
+    if tool_name == "Bash":
+        cmd = command_text("Bash", tool_input).strip()
+        if not cmd or _COMPLEX.search(cmd):
+            return None
+        words = cmd.split()
+        return ("Bash", " ".join(words[:2]) + " *")
+    if tool_name in _FILE_TOOLS or tool_name.startswith("mcp__"):
+        return (tool_name, None)
+    return None

bund/setup_chat.py

@@ -0,0 +1,149 @@
+import sys
+import threading
+import time
+
+from . import config, templates
+from .telegram import TelegramError, call, send
+
+
+def set_token(cfg: dict, token: str) -> int:
+    token = token.strip()
+    try:
+        me = call(token, "getMe", timeout=10)
+    except TelegramError as e:
+        print(f"Telegram rejected that token: {e}")
+        print("Get a fresh one from @BotFather and try again.")
+        return 1
+    cfg["token"] = token
+    config.save(cfg)
+    name = me.get("username") or "your bot"
+    print(f"Token saved. Bot: @{name}")
+    if not cfg.get("chatId"):
+        print("Next: bund set --chat auto")
+    return 0
+
+
+def set_chat_id(cfg: dict, chat_id: str) -> int:
+    chat_id = chat_id.strip()
+    if not chat_id.lstrip("-").isdigit():
+        print("Chat id must be numeric. Tip: bund set --chat auto does it for you.")
+        return 1
+    if not cfg.get("token"):
+        print("Set the token first: bund set --token <botfather-token>")
+        return 1
+    try:
+        send(
+            "bund connected ✅. This is your approval chat now.",
+            chat_id=int(chat_id),
+            cfg=cfg,
+        )
+    except TelegramError:
+        print("Telegram refused to message that chat.")
+        print("Open the bot and press Start first. Bots can't message people who haven't said hi.")
+        return 1
+    cfg["chatId"] = int(chat_id)
+    config.save(cfg)
+    print(f"Chat saved: {chat_id}")
+    return 0
+
+
+def set_chat_auto(cfg: dict) -> int:
+    if not cfg.get("token"):
+        print("Set the token first: bund set --token <botfather-token>")
+        return 1
+    while True:
+        choice = _pick_chat(cfg)
+        if choice is None:
+            return 1
+        if choice == "retry":
+            continue
+        cfg["chatId"] = choice
+        config.save(cfg)
+        try:
+            send(templates.say("setup_ok", {}), chat_id=choice, cfg=cfg)
+        except TelegramError:
+            pass
+        print(f"Chat saved: {choice}")
+        return 0
+
+
+def _pick_chat(cfg: dict):
+    try:
+        me = call(cfg["token"], "getMe", timeout=10)
+    except TelegramError as e:
+        print(f"Telegram error: {e}")
+        return None
+    username = me.get("username") or ""
+    print(f"Open https://t.me/{username} and send the bot any message.")
+    print("Waiting up to 2 minutes. Press Enter when done waiting.")
+
+    stop = threading.Event()
+
+    def _wait_enter():
+        try:
+            input()
+        except (EOFError, OSError):
+            pass
+        stop.set()
+
+    threading.Thread(target=_wait_enter, daemon=True).start()
+
+    senders = {}
+    offset = 0
+    try:
+        stale = call(cfg["token"], "getUpdates", {"timeout": 0}, timeout=10)
+        for upd in stale or []:
+            offset = max(offset, int(upd.get("update_id", 0)) + 1)
+    except TelegramError as e:
+        print(f"Telegram error: {e}")
+        return None
+
+    deadline = time.time() + 120
+    while time.time() < deadline and not stop.is_set():
+        try:
+            updates = call(
+                cfg["token"],
+                "getUpdates",
+                {"offset": offset, "timeout": 5, "allowed_updates": ["message"]},
+                timeout=10,
+            )
+        except TelegramError:
+            time.sleep(1)
+            continue
+        for upd in updates or []:
+            try:
+                offset = int(upd["update_id"]) + 1
+            except (KeyError, TypeError, ValueError):
+                continue
+            msg = upd.get("message") or {}
+            chat = msg.get("chat") or {}
+            if chat.get("type") not in (None, "private"):
+                continue
+            sender = msg.get("from") or {}
+            sid = sender.get("id") or chat.get("id")
+            if sid is None or sid in senders:
+                continue
+            name = sender.get("first_name") or sender.get("username") or "Unknown"
+            uname = f" (@{sender['username']})" if sender.get("username") else ""
+            senders[sid] = f"{name}{uname}, id {sid}"
+            print(f"{len(senders)}) {senders[sid]}")
+
+    if not senders:
+        print("No messages received. Is the bot the one you messaged?")
+        return None
+
+    try:
+        answer = input(f"Which one is you? [1-{len(senders)}, or n to retry]: ").strip()
+    except (EOFError, OSError):
+        return None
+    if answer.lower() in ("n", "no", "retry"):
+        return "retry"
+    try:
+        idx = int(answer)
+    except ValueError:
+        print("That's not a number.")
+        return None
+    if not 1 <= idx <= len(senders):
+        print(f"Pick a number between 1 and {len(senders)}.")
+        return None
+    return list(senders.keys())[idx - 1]

bund/telegram.py

@@ -0,0 +1,78 @@
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+
+API = "https://api.telegram.org/bot{token}/{method}"
+
+
+class TelegramError(Exception):
+    pass
+
+
+def call(token: str, method: str, params: dict = None, timeout: float = 15):
+    url = API.format(token=urllib.parse.quote(token), method=method)
+    data = json.dumps(params or {}).encode("utf-8")
+    req = urllib.request.Request(
+        url, data=data, headers={"Content-Type": "application/json"}
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            body = json.load(resp)
+    except (urllib.error.URLError, TimeoutError, OSError, ValueError) as e:
+        raise TelegramError(f"{method} failed: {e}") from e
+    if not isinstance(body, dict) or not body.get("ok"):
+        desc = body.get("description", "unknown error") if isinstance(body, dict) else "bad response"
+        raise TelegramError(f"{method}: {desc}")
+    return body.get("result")
+
+
+def keyboard(rows):
+    """rows: [[(text, callback_data), ...], ...] -> Telegram inline_keyboard"""
+    if not rows:
+        return None
+    return {
+        "inline_keyboard": [
+            [{"text": text, "callback_data": data} for text, data in row] for row in rows
+        ]
+    }
+
+
+def send(text: str, rows=None, chat_id=None, cfg: dict = None) -> dict:
+    cfg = cfg or {}
+    params = {
+        "chat_id": chat_id if chat_id is not None else cfg.get("chatId"),
+        "text": text,
+        "parse_mode": "HTML",
+        "disable_web_page_preview": True,
+    }
+    kb = keyboard(rows)
+    if kb:
+        params["reply_markup"] = kb
+    return call(cfg.get("token"), "sendMessage", params)
+
+
+def edit(chat_id, message_id: int, text: str, rows=None, cfg: dict = None) -> dict:
+    cfg = cfg or {}
+    params = {
+        "chat_id": chat_id,
+        "message_id": message_id,
+        "text": text,
+        "parse_mode": "HTML",
+        "disable_web_page_preview": True,
+    }
+    kb = keyboard(rows)
+    if kb:
+        params["reply_markup"] = kb
+    else:
+        params["reply_markup"] = {"inline_keyboard": []}
+    return call(cfg.get("token"), "editMessageText", params)
+
+
+def answer(callback_query_id: str, text: str = None, cfg: dict = None) -> dict:
+    cfg = cfg or {}
+    params = {"callback_query_id": callback_query_id}
+    if text:
+        params["text"] = text
+        params["show_alert"] = False
+    return call(cfg.get("token"), "answerCallbackQuery", params)

bund/templates/plain.json

@@ -0,0 +1,37 @@
+{
+  "permission": [
+    "{tool} needs your approval in {project}.",
+    "Permission request: {tool} ({project}).",
+    "Claude wants to use {tool}. Awaiting your decision."
+  ],
+  "done": [
+    "Task finished in {project}.",
+    "Done: {project} at {time}."
+  ],
+  "approved": [
+    "Approved.",
+    "Allowed."
+  ],
+  "denied": [
+    "Denied.",
+    "Rejected."
+  ],
+  "approve_all": [
+    "Rule saved. Similar commands will be allowed."
+  ],
+  "timeout": [
+    "No answer. The prompt fell back to the terminal."
+  ],
+  "setup_ok": [
+    "bund connected ✅."
+  ],
+  "dangerous": [
+    "⚠️ This command can delete or overwrite things permanently. Read it carefully."
+  ],
+  "pick_user": [
+    "Select yourself from the list below."
+  ],
+  "test": [
+    "bund test message. Setup works."
+  ]
+}

bund/templates/sarcasm.json

@@ -0,0 +1,50 @@
+{
+  "permission": [
+    "🙄 Your AI intern wants to run {tool}. Please supervise.",
+    "{tool} needs approval again. It's almost like permissions exist.",
+    "Claude would like to use {tool} in {project}. What could possibly happen?",
+    "Alert: {tool} in {project}. Your input is requested (finally).",
+    "The robot wants {tool}. You're the human. Decide, human.",
+    "Permission prompt in {project}. The agent has been staring at this for {time}.",
+    "Break whatever you're doing. {tool} can't proceed without you."
+  ],
+  "done": [
+    "✅ Claude finished in {project}. You can stop pretending you were in the meeting.",
+    "{project} is done. The agent survived without you.",
+    "Task complete in {project} at {time}. Slow clap.",
+    "All done in {project}. Your phone may now return to being a phone."
+  ],
+  "approved": [
+    "✅ Approved. Hope you actually read it.",
+    "✅ Allowed. Bold move.",
+    "✅ Go ahead. The commit history remembers everything."
+  ],
+  "denied": [
+    "❌ Denied. Claude is sulking quietly.",
+    "❌ Nope. It will try something else in 3… 2…",
+    "❌ Denied. You're the reason it can't have nice things."
+  ],
+  "approve_all": [
+    "♾ Rule saved. What could go wrong?",
+    "♾ Approved forever. Past-you trusts present-you a lot.",
+    "♾ Never ask again for this. Live dangerously."
+  ],
+  "timeout": [
+    "⌛ No answer, so Claude is back in your terminal, waiting.",
+    "⌛ You ghosted it. Claude returned to the terminal.",
+    "⌛ Timeout. The agent resurfaces in your terminal."
+  ],
+  "setup_ok": [
+    "✅ bund connected. You can now be bothered from anywhere.",
+    "✅ Connected. Your phone now belongs to the agent."
+  ],
+  "dangerous": [
+    "⚠️ This command can delete or overwrite things permanently. Read it carefully."
+  ],
+  "pick_user": [
+    "Pick yourself from the list below. Strangers don't get to approve anything."
+  ],
+  "test": [
+    "📡 bund test message. If you can read this, your phone is officially part of the pipeline."
+  ]
+}

bund/templates.py

@@ -0,0 +1,47 @@
+import json
+import random
+from pathlib import Path
+
+from . import config
+
+PKG_DIR = Path(__file__).resolve().parent / "templates"
+
+_FALLBACK = {"permission": ["{tool} needs approval."], "done": ["Done in {project}."]}
+
+
+def _load_pool(tone: str) -> dict:
+    pool = {}
+    try:
+        with open(PKG_DIR / f"{tone}.json", encoding="utf-8") as f:
+            data = json.load(f)
+        if isinstance(data, dict):
+            pool.update(data)
+    except (OSError, json.JSONDecodeError):
+        pass
+    try:
+        with open(config.config_dir() / "templates.json", encoding="utf-8") as f:
+            overrides = json.load(f)
+        if isinstance(overrides, dict):
+            for key, val in overrides.items():
+                if isinstance(val, list) and val:
+                    pool[key] = val
+                elif isinstance(val, str):
+                    pool[key] = [val]
+    except (OSError, json.JSONDecodeError):
+        pass
+    if not pool:
+        pool = dict(_FALLBACK)
+    return pool
+
+
+def say(event: str, vars: dict = None, tone: str = None) -> str:
+    if tone is None:
+        tone = (config.load().get("tone") or "sarcasm").strip()
+    if tone not in ("sarcasm", "plain"):
+        tone = "sarcasm"
+    pool = _load_pool(tone)
+    lines = pool.get(event) or _FALLBACK.get(event) or [event]
+    line = random.choice(lines)
+    for key, val in (vars or {}).items():
+        line = line.replace("{" + str(key) + "}", str(val))
+    return line

bund-0.1.0.dist-info/METADATA

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: bund
+Version: 0.1.0
+Summary: Telegram pings for coding agents. Approve from your phone. Free. Zero dependencies.
+License: MIT
+Keywords: telegram,claude,coding-agent,hooks,notifications,approval
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<h1 align="center">bund</h1>
+
+<p align="center"><b>Your AI agent is waiting for you. Again.</b></p>
+
+<p align="center">
+  <img src="https://api.memegen.link/images/fine/claude_has_been_waiting_for_2_hours/this_is_fine.png?width=450" width="450" alt="this is fine">
+</p>
+
+<p align="center">
+  Telegram pings for coding agents.<br>
+  Approve from your phone. Free. Zero dependencies.
+</p>
+
+---
+
+## The problem
+
+<p align="center">
+  <img src="https://api.memegen.link/images/db/you/agent_needing_approval/just_one_more_meeting.png?width=450" width="450" alt="distracted boyfriend">
+</p>
+
+## How it works
+
+<p align="center">
+  <img src="https://api.memegen.link/images/gru/claude_asks_permission/bund_pings_your_telegram/you_tap_approve_from_anywhere/claude_keeps_working.png?width=450" width="450" alt="gru plan">
+</p>
+
+## Setup (2 minutes)
+
+```bash
+pip install bund
+
+bund set --token <botfather-token>
+bund set --chat auto
+bund install
+bund test
+```
+
+`bund install` wires Claude Code's `PermissionRequest` and `Stop` hooks. On any
+other agent or script, use `bund ask` (below) — no install needed.
+
+<p align="center">
+  <img src="https://api.memegen.link/images/success/set_up_in_two_minutes/phone_buzzed_immediately.png?width=400" width="400" alt="success kid">
+</p>
+
+## What you get
+
+| Button | Does |
+|---|---|
+| ✅ Approve | Lets it run, once |
+| ❌ Deny | Nope |
+| ♾ Approve all similar | Never asks again for that kind of command |
+
+And a ping when the task is done:
+
+<p align="center">
+  <img src="https://api.memegen.link/images/fry/not_sure_if_agent_finished/or_waiting_for_my_approval.png?width=450" width="450" alt="fry">
+</p>
+
+Now you know which one.
+
+## Sample message
+
+```
+🙄 Your AI intern wants to run Bash. Please supervise.
+
+📁 my-project
+npm run build
+
+[ ✅ Approve ] [ ❌ Deny ]
+[ ♾ Approve all similar: Bash(npm run *) ]
+```
+
+The joke is on top. The real command is always shown in full below it.
+
+## Works with any agent
+
+`bund ask` is the universal protocol: any CLI, script, or agent asks a
+question, your phone answers.
+
+```bash
+bund ask "deploy to prod?" && echo let's go
+# stdout: allow | deny | timeout
+# exit:   0      1      2
+```
+
+```python
+import subprocess
+r = subprocess.run(["bund", "ask", "run the migration?"], capture_output=True, text=True)
+if r.stdout.strip() == "allow":
+    ...
+```
+
+No config files to wire. If bund isn't configured, `bund ask` fails fast with
+exit code 2 instead of hanging your agent.
+
+## Safety
+
+<p align="center">
+  <img src="https://api.memegen.link/images/drake/approve_all_for_rm_rf/no_button_for_dangerous_commands.png?width=400" width="400" alt="drake">
+</p>
+
+- Only **your** Telegram chat can approve anything
+- Every button works once (random request ids, no replaying old taps)
+- Dangerous commands (`rm -rf`, `sudo`, force pushes, `curl | sh`, …) get a
+  serious warning and **no** "approve all" button
+- No answer? The agent falls back to the normal terminal prompt
+- bund can never block your work — any error means silent fallback
+- Token and chat id live in `~/.config/bund/config.json` with `chmod 600`
+
+## Dependencies
+
+<p align="center">
+  <img src="https://api.memegen.link/images/buzz/zero_dependencies/zero_dependencies_everywhere.png?width=400" width="400" alt="buzz">
+</p>
+
+Python 3.9+. Standard library only. That's it.
+
+## Cost
+
+<p align="center">
+  <img src="https://api.memegen.link/images/oprah/you_get_a_free_bot/and_you_get_free_approvals.gif?width=400" width="400" alt="oprah">
+</p>
+
+## Tone
+
+```bash
+bund set --tone sarcasm   # default
+bund set --tone plain     # for people who have no joy
+```
+
+Add your own lines in `~/.config/bund/templates.json`.
+
+## Also
+
+```bash
+bund -m "build finished, come back"
+```
+
+Works with any script or agent.
+
+<p align="center">
+  <img src="https://api.memegen.link/images/pigeon/claude/_/is_this_a_permission_prompt~q.png?width=400" width="400" alt="is this a pigeon">
+</p>
+
+---
+
+**Commands**
+
+```
+bund set --token <token>        # botfather token
+bund set --chat auto|<id>       # pick your chat
+bund set --tone sarcasm|plain   # message tone
+bund install                    # add Claude Code hooks
+bund uninstall                  # remove only bund's hooks
+bund test                       # send a test message
+bund ask "<question>"           # ask anything (allow|deny|timeout)
+bund -m "<text>"                # send any message
+bund hook                       # internal, called by hooks
+```
+
+<p align="center">
+  <sub>Memes by <a href="https://memegen.link">memegen.link</a>. If they don't load, that's on them, not us.</sub><br>
+  <sub>MIT License</sub>
+</p>

bund-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+bund/__init__.py,sha256=7y4S6U5UpUBcVTsjI7GdnTGCexXbW0qFIcIf0hp4sL4,97
+bund/__main__.py,sha256=bYt9eEaoRQWdejEHFD8REx9jxVEdZptECFsV7F49Ink,30
+bund/ask.py,sha256=3AF3hUCtA_m3U7m7dp_vBbFuZhACBBxX2F2jGpaacHg,1242
+bund/cli.py,sha256=X912kzHB6PKls1OL1orh646M-Y4XY5X45d8G4MQavBs,3976
+bund/config.py,sha256=kELcky5OfarF3cBblMmGJZBhYwVnPXBLcCduQJsxSOo,1220
+bund/hook.py,sha256=Pimz6Mv6_X1YKu4bO5qp8lp8mVn85oQ46kkg4u3BYjY,5637
+bund/install.py,sha256=VGqhoWa2tQ8tDKcE0zIHRQlXSZfDtyOP56ACKuPCg7s,3746
+bund/poller.py,sha256=jiyEwotwrS3LYTbpNbf0DTN53Tz14SRdKTGJIvzGijk,4622
+bund/rules.py,sha256=KVINVv5uhgTeJ-FZIO8d4NvIYQji9Cb8589DGim0mCA,1678
+bund/setup_chat.py,sha256=NrsNwUA8GROf87qijTExctY15ajFBjDBFXMzCMriPM4,4662
+bund/telegram.py,sha256=VHDmAPRmGzDkGKmM6gCWIYemK3MdQYyKcdISerplTEw,2446
+bund/templates.py,sha256=XyBWDDt91kdAC-Pc7_VDKQgVZxjZISYj6T_4so2QCdM,1462
+bund/templates/plain.json,sha256=AE5q9DsOyTHwwmsdP8lzvMgzLwZfzKtAmML6z1oo-V4,796
+bund/templates/sarcasm.json,sha256=qtauLqeHti-OGf1Tit_VZHrYrz_zqXVhXT6TV-zb-6c,2041
+bund-0.1.0.dist-info/licenses/LICENSE,sha256=TKcQSMayTxQN86iL-m-AzTxuQEke5UX4VLoZ6-AVSwQ,1074
+bund-0.1.0.dist-info/METADATA,sha256=aoOQvekq2iyqtEq4WKtv0I5ZAXTF-efVxU_ft1X2l8Q,5461
+bund-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+bund-0.1.0.dist-info/entry_points.txt,sha256=Kz9ZDSSGhTMgGqHFenS4nDyzo2qO0bjTHmu8G3guPSc,39
+bund-0.1.0.dist-info/top_level.txt,sha256=DiVbXwtj2f-zGCxX0I6b5RXHInHR0oRuKPkKgSdZqmc,5
+bund-0.1.0.dist-info/RECORD,,

bund-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

bund-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bund = bund.cli:main

bund-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bund contributors
+
+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.

bund-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+bund