{"id":51048449,"url":"https://github.com/edumntg/claude-beep","last_synced_at":"2026-06-22T15:31:12.259Z","repository":{"id":365552785,"uuid":"1272523744","full_name":"edumntg/claude-beep","owner":"edumntg","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-17T20:11:57.000Z","size":144,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-17T22:12:15.141Z","etag":null,"topics":["agents","claude","claude-code","claude-plugin","cli","discord","notifications","slack","telegram"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/edumntg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-17T17:34:38.000Z","updated_at":"2026-06-17T20:13:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/edumntg/claude-beep","commit_stats":null,"previous_names":["edumntg/claude-beep"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/edumntg/claude-beep","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edumntg%2Fclaude-beep","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edumntg%2Fclaude-beep/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edumntg%2Fclaude-beep/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edumntg%2Fclaude-beep/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/edumntg","download_url":"https://codeload.github.com/edumntg/claude-beep/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edumntg%2Fclaude-beep/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34655701,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-22T02:00:06.391Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","claude","claude-code","claude-plugin","cli","discord","notifications","slack","telegram"],"created_at":"2026-06-22T15:31:11.536Z","updated_at":"2026-06-22T15:31:12.245Z","avatar_url":"https://github.com/edumntg.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# claude-beep\n\n\u003e Two-way Claude Code notifications for Telegram, Discord, and Slack.\n\u003e Get pinged when Claude finishes a turn. Reply from your phone to keep it moving.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](package.json)\n[![Tests](https://img.shields.io/badge/tests-87%20passing-success)](#)\n[![Status](https://img.shields.io/badge/status-1.0.0-orange)](#)\n\n```\n✅ Claude finished · api · 12.5s\n\n📁 ~/work/api\n⏱ 12.5s\n🔖 api\n\n│ Refactored the auth module. Migrated session storage from in-memory\n│ to Redis. All 47 tests pass.\n\nReply to this message, or send \"@api \u003cmessage\u003e\", to target this session.\n```\n\n---\n\n## Why\n\nClaude Code sessions can take minutes. Sitting at the terminal waiting for them to finish (or to ask for permission) is a waste of attention. claude-beep:\n\n- **Pings your phone** the moment Claude is done — with the last line of its response inline, plus a link to the full text if it's long.\n- **Routes your reply back** into the running session as the next user turn. Type `@api what about the lockfile?` from Telegram and it lands in your terminal.\n- **Handles many sessions in parallel.** Name them at launch (`claude-beep run --name api -- claude`) and mention them by name in chat.\n- **Stays local.** Tokens never leave `~/.claude-beep/env` (perms `0600`). No SaaS, no relay server, no telemetry.\n\n---\n\n## Install\n\n**From GitHub** (works today, no npm publish required):\n\n```bash\nnpm install -g github:edumntg/claude-beep\n```\n\nThat clones the repo, builds it, and puts `claude-beep` on your `PATH`. Verify with `claude-beep --version`.\n\n**From npm** (once published):\n\n```bash\nnpm install -g claude-beep\n```\n\n**For development** — clone and link:\n\n```bash\ngit clone https://github.com/edumntg/claude-beep.git\ncd claude-beep\nnpm install\nnpm link\n```\n\nRequires **Node 20+** and **Claude Code** (any version with `hooks` support).\n\n---\n\n## Quick start\n\nThe fastest path is the interactive wizard:\n\n```bash\nclaude-beep init\n```\n\nIt walks you through:\n1. Picking a transport (Telegram / Discord / Slack)\n2. Creating a bot (step-by-step, one instruction at a time, with `Enter`-to-continue)\n3. Saving tokens to `~/.claude-beep/env` (perms `0600`)\n4. Validating the bot, looking up your chat/channel/user IDs automatically (Telegram)\n5. Sending a test message\n6. Registering Claude Code hooks in `~/.claude/settings.json`\n7. Installing the daemon as a background service (optional)\n\nWhen the wizard finishes, you're one command away:\n\n```bash\nclaude-beep run --name myproj -- claude\n```\n\nUse Claude normally. When a turn ends you'll get a chat ping. Reply from chat → injected into the session.\n\n---\n\n## Features\n\n- **Outbound notifications** — every Claude turn ends with a structured message containing the project, duration, session label, and last assistant text.\n- **Inbound replies** — type in chat, the daemon injects it into the originating PTY as if you typed it yourself.\n- **Three transports** — Telegram (long-poll), Discord (Gateway), Slack (Socket Mode). All outbound + inbound.\n- **Multi-session routing** — three ways to target a specific session:\n  - `@\u003cname\u003e \u003cmessage\u003e` — mention a named session\n  - Reply to a notification — uses your chat client's \"reply to message\" feature\n  - Plain message — falls back to the most recently active session\n- **Bot commands** — send `/sessions`, `/status`, `/help` in chat to query the daemon.\n- **Long-message offload** — when Claude's response is longer than the chat's message cap, the full text is uploaded to a pastebin (dpaste or GitHub Gist, opt-in) and the chat shows a preview + link.\n- **Secret scrubber** — outbound messages have common token patterns (`Bearer …`, `sk-…`, `ghp_…`, `*_TOKEN=…`, etc.) redacted before send.\n- **Sensitive-path denylist** — events from `.env*`, `credentials/`, `secrets/`, `*.pem`, `*.key` paths are dropped before formatting.\n- **Daemon supervision** — `claude-beep service install` writes a `launchd` plist (macOS) or `systemd --user` unit (Linux). Reads tokens from `~/.claude-beep/env`.\n- **Wrapper auto-reconnect** — if the daemon restarts, the PTY wrapper reconnects with backoff and re-registers the same session.\n\n---\n\n## How it works\n\n```\nTerminal                              Daemon                    Chat\n────────                              ──────                    ────\n\nclaude-beep run --name api          ┌──────────────┐\n   |                                │              │            ┌──────────┐\n   | hook fires on Stop  ──────────►│  claude-beep │  send  ──►│ Telegram │\n   |                                │   daemon     │            │ Discord  │\n   | inject reply (PTY stdin)  ◄────│              │  poll  ◄──│ Slack    │\n   v                                └──────────────┘            └──────────┘\nClaude Code (in PTY)\n```\n\n1. `claude-beep run` spawns Claude inside a PTY and registers a session with the daemon over a local Unix socket.\n2. When a hook fires (Stop, Notification, etc.), a thin `claude-beep hook` command forwards the JSON payload to the daemon.\n3. The daemon routes the event by `cwd` to a transport, formats it for the platform (HTML for Telegram, Markdown for Discord, blocks for Slack), and sends.\n4. Inbound listeners on each transport receive your replies, filter by `allowed_senders`, and write to the matching session's PTY stdin.\n\nFull design rationale and decision log: [docs/PRD.md](docs/PRD.md).\n\n---\n\n## Documentation\n\n| Guide | What's inside |\n|---|---|\n| [docs/TELEGRAM.md](docs/TELEGRAM.md) | Telegram bot creation, two-way verification, troubleshooting |\n| [docs/DISCORD.md](docs/DISCORD.md) | Discord application + bot setup, OAuth invite, reply-to routing |\n| [docs/SLACK.md](docs/SLACK.md) | Slack app + Socket Mode, scopes, thread-based routing |\n| [docs/TEST_PLAN.md](docs/TEST_PLAN.md) | Manual verification plan for every phase |\n| [docs/PRD.md](docs/PRD.md) | Original design doc with architecture rationale |\n\n---\n\n## CLI reference\n\n| Command | What it does |\n|---|---|\n| `claude-beep init` | Interactive onboarding wizard (transport pick, bot creation, hooks, service install). |\n| `claude-beep init --hooks-only` | Skip the wizard; only register Claude Code hooks. |\n| `claude-beep config` | Interactive config tweaks (or pass flags: `--transport`, `--bot-token`, `--chat-id`, `--allowed-senders`, `--pastebin-enable`, ...). |\n| `claude-beep config --show` | Print current config and saved env vars with tokens masked. |\n| `claude-beep daemon --foreground` | Run the daemon in the current terminal. Use `--dry-run` to log messages instead of sending. |\n| `claude-beep run [--name N] -- \u003ccmd\u003e` | Spawn a PTY-wrapped Claude session for two-way replies. |\n| `claude-beep status` | Live daemon status: pid, uptime, active sessions, transports. |\n| `claude-beep tail` | Follow `~/.claude-beep/logs/daemon.log` (Ctrl-C to exit). |\n| `claude-beep service \u003caction\u003e` | `install`, `start`, `stop`, `uninstall`, `status` — launchd on macOS, systemd-user on Linux. |\n| `claude-beep hook \u003cevent\u003e` | Hook entry point. Invoked automatically by Claude Code via `~/.claude/settings.json`. |\n\n---\n\n## Config quick reference\n\n`~/.claude-beep/config.yaml`:\n\n```yaml\ndefault_transport: telegram\n\ntransports:\n  telegram:\n    bot_token_env: TELEGRAM_BOT_TOKEN\n    default_chat_id: \"344242056\"\n    allowed_senders: [\"344242056\"]\n\nrouting:\n  - match: { cwd: \"**\" }\n    transport: telegram\n\nfilters:\n  notify_event_types: [\"stop\", \"subagent-stop\"]   # suppress only Notification (permission prompts) by default\n  min_turn_seconds: 0\n  notify_on_error: true\n  quiet_hours: []\n\nsecurity:\n  scrub_tokens: true\n  sensitive_paths: [\"**/.env\", \"**/.env.*\", \"**/credentials/**\", \"**/secrets/**\"]\n\npastebin:\n  enabled: false               # opt-in for long-message offload\n  provider: dpaste             # or \"gist\"\n  threshold_chars: 1000\n```\n\nTokens live in `~/.claude-beep/env` (auto-loaded by the daemon). Never put them in `config.yaml`.\n\n---\n\n## Multi-session example\n\n```bash\n# Terminal A\nclaude-beep run --name api -- claude\n\n# Terminal B\nclaude-beep run --name ui -- claude\n\n# Terminal C — see what's running\nclaude-beep status\n# or, from Telegram:\n/sessions\n```\n\nFrom your phone:\n```\n@api please rerun the failed test\n@ui  the lint config is wrong, fix it\n```\n\nEach message is routed to its named session. Plain messages (no `@`) go to whichever session was most recently active.\n\n---\n\n## Security\n\n- **Tokens** live in `~/.claude-beep/env`, `0600`. Not in `config.yaml`.\n- **IPC socket** is `0600`. Only your UID can connect.\n- **Inbound auth** — replies are accepted only from `allowed_senders`. Empty list disables inbound.\n- **Daemon has no inbound network ports.** All transport I/O is outbound (long-poll / WebSocket / Socket Mode).\n- **Scrubber** redacts token-shaped strings before send. Customise with `security.scrub_extra_patterns`.\n- **Sensitive-path denylist** drops events from sensitive directories before formatting.\n\n---\n\n## Known limitations\n\n- **Interactive Claude prompts** (multi-choice menus, permission popups inside Claude's TUI) are rendered with arrow-key navigation and don't translate into chat. You'll see Claude is waiting via the `/sessions` command or by checking the terminal; respond with a number/text answer if Claude is asking that style of question, otherwise navigate at the terminal.\n- **Telegram has a 4096-char message cap; Discord 2000; Slack ~3000 per block.** Enable the pastebin layer (`claude-beep config --pastebin-enable`) to offload long responses.\n- **Single-user model.** The current routing/auth model assumes one operator. Multi-user team usage is on the roadmap.\n\n---\n\n## Roadmap\n\n- [ ] Inline reply buttons (Telegram inline keyboards, Discord components, Slack actions)\n- [ ] Alternative session host built on `@anthropic-ai/claude-agent-sdk` (no PTY wrapper)\n- [ ] Additional transports (ntfy, Matrix, Pushover, generic webhook)\n- [ ] Web dashboard for live session view\n- [ ] Multi-machine routing via a self-hosted relay\n- [ ] Multi-user / team mode with per-user session permissions\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/edumntg/claude-beep.git\ncd claude-beep\nnpm install\nnpm test          # 87 tests\nnpm run build\nnpm run dev -- daemon --foreground   # run from source\n```\n\nThe `prepare` lifecycle compiles TS to `dist/` on install. The `postinstall` step fixes the `node-pty` spawn-helper executable bit on macOS.\n\n---\n\n## Contributing\n\nIssues and PRs welcome at \u003chttps://github.com/edumntg/claude-beep\u003e. Before opening a feature PR, please open an issue first to discuss scope.\n\nWhen reporting a bug, please include:\n- `claude-beep --version`\n- `claude-beep config --show` (tokens auto-masked)\n- Last ~50 lines of `~/.claude-beep/logs/daemon.log`\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\nMade by [@edumntg](https://github.com/edumntg).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedumntg%2Fclaude-beep","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedumntg%2Fclaude-beep","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedumntg%2Fclaude-beep/lists"}