{"id":51255678,"url":"https://github.com/ssamssae/claude-telegram-kit","last_synced_at":"2026-06-29T10:02:14.864Z","repository":{"id":365512330,"uuid":"1272383618","full_name":"ssamssae/claude-telegram-kit","owner":"ssamssae","description":"Telegram reply-enforcement hooks for Claude Code — never get a silent terminal-only answer on your phone again.","archived":false,"fork":false,"pushed_at":"2026-06-17T16:06:13.000Z","size":16,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-17T18:06:32.334Z","etag":null,"topics":["anthropic","claude","claude-code","claude-code-plugin","hooks","telegram","telegram-bot"],"latest_commit_sha":null,"homepage":null,"language":"Shell","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/ssamssae.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-17T14:57:36.000Z","updated_at":"2026-06-17T16:06:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ssamssae/claude-telegram-kit","commit_stats":null,"previous_names":["ssamssae/claude-telegram-kit"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ssamssae/claude-telegram-kit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssamssae%2Fclaude-telegram-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssamssae%2Fclaude-telegram-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssamssae%2Fclaude-telegram-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssamssae%2Fclaude-telegram-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ssamssae","download_url":"https://codeload.github.com/ssamssae/claude-telegram-kit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssamssae%2Fclaude-telegram-kit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34921807,"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-29T02:00:05.398Z","response_time":58,"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":["anthropic","claude","claude-code","claude-code-plugin","hooks","telegram","telegram-bot"],"created_at":"2026-06-29T10:02:09.791Z","updated_at":"2026-06-29T10:02:14.858Z","avatar_url":"https://github.com/ssamssae.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# claude-telegram-kit\n\n**Run Claude Code from your phone over Telegram, and make sure it actually answers.**\n\nThis repository packages three dependency-light Claude Code hooks as a\nClaude Code plugin:\n\n| Hook | What it does |\n|------|--------------|\n| 🔁 `telegram-reply-check.sh` | If a turn started from Telegram but Claude never called the reply tool, block the stop and force it to reply. |\n| 🚧 `telegram-ui-guard.sh` | Blocks `AskUserQuestion` / `ExitPlanMode` / `EnterPlanMode` during a Telegram turn, because those terminal UI boxes are invisible from Telegram. |\n| 🏷️ `session-device-id.sh` | Optional. Adds a per-machine prefix instruction so replies can identify which machine answered. |\n\nThe Telegram MCP bridge is intentionally **not** copied into this repo. Use the\nofficial `telegram@claude-plugins-official` channel plugin for bot token storage,\npairing, allowlists, and the MCP server. This kit installs the hooks around that\nbridge.\n\n## Fresh Machine Install\n\n### 1. Install prerequisites\n\n```bash\ncommand -v jq \u003e/dev/null || brew install jq\ncommand -v bun \u003e/dev/null || curl -fsSL https://bun.sh/install | bash\n```\n\n### 2. Install the official Telegram channel plugin\n\nIn Claude Code:\n\n```text\n/plugin install telegram@claude-plugins-official\n/reload-plugins\n/telegram:configure \u003cBOT_TOKEN_FROM_BOTFATHER\u003e\n```\n\nThen message the bot from Telegram and complete the pairing flow in Claude Code:\n\n```text\n/telegram:access pair \u003cPAIRING_CODE\u003e\n/telegram:access policy allowlist\n```\n\n### 3. Install this hook kit as a Claude Code plugin\n\nFrom a shell on the new machine:\n\n```bash\ngit clone git@github.com:ssamssae/claude-telegram-kit.git ~/claude-telegram-kit\ncd ~/claude-telegram-kit\n./scripts/validate-plugin.sh\nclaude plugin marketplace add ~/claude-telegram-kit\nclaude plugin install claude-telegram-kit@claude-telegram-kit --scope user\n```\n\nStart Claude Code with the Telegram channel enabled:\n\n```bash\nclaude --channels plugin:telegram@claude-plugins-official\n```\n\nAfter install, Claude Code loads `hooks/hooks.json` from this plugin. The hook\ncommands use `${CLAUDE_PLUGIN_ROOT}`, so they keep working from the plugin cache\ninstead of depending on `~/.claude/hooks`.\n\n### 4. Optional device prefixes\n\nFor a plugin install, keep local per-machine labels outside the plugin cache:\n\n```bash\nmkdir -p ~/.claude/claude-telegram-kit\ncp ~/claude-telegram-kit/hooks/devices.conf.example ~/.claude/claude-telegram-kit/devices.conf\n```\n\nEdit `~/.claude/claude-telegram-kit/devices.conf`:\n\n```text\nmy-laptop*|💻|laptop\nmy-desktop*|🖥|desktop\nmy-server*|🏭|server\n*|📱|unknown\n```\n\nEach line is `hostname_glob|emoji|label`; the first glob matching `hostname`\nwins. Single-machine users can skip the file and set\n`TELEGRAM_DEVICE_EMOJI` / `TELEGRAM_DEVICE_LABEL` in their environment.\n\n## Legacy Manual Install\n\nThe plugin install above is preferred for new machines. The old manual hook copy\nflow is still supported:\n\n```bash\ngit clone git@github.com:ssamssae/claude-telegram-kit.git\ncd claude-telegram-kit\n./install.sh\n```\n\nThen merge the hook blocks from [`settings.example.json`](settings.example.json)\ninto `~/.claude/settings.json`.\n\n## Reply Tool Name\n\nThe hooks default to the official Telegram channel reply tool:\n\n```text\nmcp__plugin_telegram_telegram__reply\n```\n\nIf your Telegram plugin exposes a different reply tool, set\n`TELEGRAM_REPLY_TOOL` in your environment. See\n[`telegram.env.example`](telegram.env.example).\n\n## How Reply Enforcement Works\n\n1. On every `Stop`, the hook reads the session transcript.\n2. It finds the last real user prompt and checks for the\n   `plugin:telegram:telegram` channel marker.\n3. It counts reply-tool calls after that prompt.\n4. Zero calls blocks the stop and asks Claude to reply through Telegram. One or\n   more calls let the turn end.\n\nFailure paths exit `0`, so a broken hook should not wedge a session. The Stop\nhook also honors `stop_hook_active` to avoid block loops.\n\n## Validation\n\nRun the local validation suite before committing:\n\n```bash\n./tests/run.sh\n```\n\n`tests/run.sh` validates the plugin manifest, hook schema, hook path resolution,\nand the core behavior of all three hooks without using Telegram secrets. Also\nrun the directive-provided forbidden-literal scan from the repository root before\ncommitting.\n\n## Security\n\n- This kit never needs your Telegram bot token or chat identifier.\n- The official Telegram plugin stores its own channel configuration.\n- Keep local per-machine labels in `~/.claude/claude-telegram-kit/devices.conf`\n  or environment variables, not in this repository.\n- `telegram.env` and `hooks/devices.conf` are gitignored for legacy manual\n  installs.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fssamssae%2Fclaude-telegram-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fssamssae%2Fclaude-telegram-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fssamssae%2Fclaude-telegram-kit/lists"}