bund 0.1.0__tar.gz

bund-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,165 @@
+<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/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bund"
+version = "0.1.0"
+description = "Telegram pings for coding agents. Approve from your phone. Free. Zero dependencies."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["telegram", "claude", "coding-agent", "hooks", "notifications", "approval"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Quality Assurance",
+]
+
+[project.scripts]
+bund = "bund.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+bund = ["templates/*.json"]

bund-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

bund-0.1.0/src/bund/__init__.py

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

bund-0.1.0/src/bund/__main__.py

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

bund-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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