{"id":43713286,"url":"https://github.com/edgarjs/claudio","last_synced_at":"2026-02-08T01:04:42.509Z","repository":{"id":336498215,"uuid":"1148229206","full_name":"edgarjs/claudio","owner":"edgarjs","description":"Claudio is a Telegram-to-Claude Code bridge","archived":false,"fork":false,"pushed_at":"2026-02-05T04:34:14.000Z","size":902,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-05T04:47:31.289Z","etag":null,"topics":["ai","bash","claude","cli","code","llm","remote","shell","telegram"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/edgarjs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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-02-02T18:17:09.000Z","updated_at":"2026-02-05T04:34:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/edgarjs/claudio","commit_stats":null,"previous_names":["edgarjs/claudio"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/edgarjs/claudio","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edgarjs%2Fclaudio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edgarjs%2Fclaudio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edgarjs%2Fclaudio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edgarjs%2Fclaudio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/edgarjs","download_url":"https://codeload.github.com/edgarjs/claudio/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edgarjs%2Fclaudio/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29114951,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-05T05:31:32.482Z","status":"ssl_error","status_checked_at":"2026-02-05T05:31:29.075Z","response_time":65,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ai","bash","claude","cli","code","llm","remote","shell","telegram"],"created_at":"2026-02-05T07:00:46.728Z","updated_at":"2026-02-05T07:01:13.481Z","avatar_url":"https://github.com/edgarjs.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claudio\n\n![](header.png)\n\nClaudio is an adapter for Claude Code CLI and Telegram. It makes a tunnel between a private network and Telegram's API. So that users can chat with Claude Code remotely, in a safe way.\n\n```\n                       +---------------------------------------------+\n                       |              Remote Machine                 |\n                       |                                             |\n                       |                                             |\n  +----------+         |    +---------+       +-----------------+    |\n  | Telegram |\u003c--------+---\u003e| Claudio |\u003c-----\u003e| Claude Code CLI |    |\n  +----------+         |    +---------+       +-----------------+    |\n                       +---------------------------------------------+\n```\n\n[![CI](https://github.com/edgarjs/claudio/actions/workflows/ci.yml/badge.svg)](https://github.com/edgarjs/claudio/actions/workflows/ci.yml)\n\n---\n\n## Overview\n\nClaudio starts a local HTTP server that listens on port 8421, and creates a tunnel using [cloudflared](https://github.com/cloudflare/cloudflared). When the user sends a message from Telegram, it's sent to `\u003ccloudflare-tunnel-url\u003e/telegram/webhook` and forwarded to the Claude Code CLI.\n\nThe user message is passed as a one-shot prompt, along with some context to maintain continuity. The last 100 messages are kept by default (configurable via `MAX_HISTORY_LINES`).\n\nAfter Claude Code finishes, it outputs the response in plain text to stdout for Claudio to capture it and forward it to Telegram API.\n\n---\n\n## Installation\n\n### **CAUTION: Security Risk**\n\nThe whole purpose of Claudio is to give you remote access to Claude Code from your Telegram app — without breaking Anthropic's Terms of Service. This means Claude Code runs with full permissions by design:\n\n**⚠️ CLAUDE CODE IS EXECUTED WITH `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, AND `--disable-slash-commands`**\n\n**The environment variable `IS_SANDBOX=1` is also set to bypass the root user restriction.**\n\nThese flags are intentional. Since there's no human in front of the terminal to approve permission prompts, Claude Code must run autonomously. Claudio mitigates the risk through: webhook secret validation (HMAC), single authorized `chat_id`, and binding the HTTP server to localhost only (external access goes through cloudflared).\n\n### Requirements\n\n- Claude Code CLI (with Pro/Max subscription)\n- Linux/macOS/WSL\n- Telegram bot token\n- Homebrew (macOS only, for installing dependencies)\n- `python3`, `curl`\n- `sqlite3`, `jq`, `cloudflared` (auto-installed if missing)\n\n### Setup\n\n1. Clone the repository and run the install command:\n\n```bash\ngit clone https://github.com/edgarjs/claudio.git\ncd claudio\n./claudio install\n```\n\nThis will:\n\n- Install dependencies (`sqlite3`, `jq`, `cloudflared`) if not already present\n- Create a symlink at `~/.local/bin/claudio` so you can run `claudio` from anywhere\n- Set up a Cloudflare **named tunnel** (permanent URL, requires a free Cloudflare account)\n- Install a systemd/launchd service\n\n\u003e **Note:** If `~/.local/bin` is not in your PATH, you'll need to add it. See the installation output for instructions.\n\n2. Set up Telegram bot\n\nIn Telegram, message `@BotFather` with `/newbot` and follow instructions to create a bot. At the end, you'll be given a secret token, copy it and then run:\n\n```bash\nclaudio telegram setup\n```\n\nPaste your Telegram token when asked, and press Enter. Then, send a `/start` message to your bot from the Telegram account that you'll use to communicate with Claude Code.\n\nThe setup wizard will confirm when it receives the message and finish. Once done, the service restarts automatically, and you can start chatting with Claude Code.\n\n\u003e For security, only the `chat_id` captured during setup is authorized to send messages.\n\n\u003e A cron job runs every 5 minutes to verify the webhook is registered and re-registers it if needed.\n\n### Status\n\nCheck the service and webhook status:\n\n```bash\nclaudio status\n```\n\n### Update\n\nTo update Claudio to the latest stable release:\n\n```bash\nclaudio update\n```\n\n### Logs\n\nTo view recent logs (default 50 lines):\n\n```bash\nclaudio log\n```\n\nFollow logs in real time with `-f`, or change the line count with `-n`:\n\n```bash\nclaudio log -f\nclaudio log -n 100\n```\n\n### Uninstall\n\nTo stop and remove the service run:\n\n```bash\nclaudio uninstall\n```\n\nIf you want to remove the `$HOME/.claudio` directory completely, run:\n\n```bash\nclaudio uninstall --purge\n```\n\n---\n\n## Customization\n\n### Model\n\nClaudio uses Haiku by default. If you want to switch to another model, just send the name of the model as a command: `/opus`, `/sonnet`, or `/haiku`. And then continue chatting.\n\n### Images\n\nYou can send photos or image files directly to Claudio. Include an optional caption to tell Claude what to do with the image, or send it without a caption and Claude will describe it.\n\n- **Supported formats:** JPEG, PNG, GIF, WebP\n- **Sending as photo:** Telegram compresses images automatically\n- **Sending as document:** Attach an image file for lossless quality\n- **Size limit:** 20 MB (Telegram bot API constraint)\n\nImages are validated (magic byte verification, size check) and stored temporarily during processing, then deleted immediately after Claude responds.\n\n### System Prompt\n\nClaudio appends a system prompt that defines its persona, core principles, and communication style (optimized for chat). The default is generated on first run at `$HOME/.claudio/SYSTEM_PROMPT.md`. You can customize it by editing that file — it's read at runtime so no need to restart.\n\n### Configuration\n\nClaudio stores its configuration and other files in `$HOME/.claudio/`. Settings are managed in the `service.env` file within that directory. After any manual edits, restart to apply your changes:\n\n```bash\nclaudio restart\n```\n\n#### Environment Variables\n\nThe following variables can be set in `$HOME/.claudio/service.env`:\n\n**Server**\n\n- `PORT` — HTTP server listening port. Default: `8421`.\n\n**Claude**\n\n- `MODEL` — Claude model to use. Accepts `haiku`, `sonnet`, or `opus`. Default: `haiku`. Can also be changed at runtime via Telegram commands `/haiku`, `/sonnet`, `/opus`.\n- `MAX_HISTORY_LINES` — Maximum number of conversation messages to keep in the database. Older messages are trimmed automatically. Default: `100`.\n\n**Telegram**\n\n- `TELEGRAM_BOT_TOKEN` — Telegram Bot API token. Set automatically during `claudio telegram setup`.\n- `TELEGRAM_CHAT_ID` — Authorized Telegram chat ID. Only messages from this chat are processed. Set automatically during `claudio telegram setup`.\n- `WEBHOOK_URL` — Public URL where Telegram sends webhook updates (e.g. `https://claudio.example.com`). Set automatically when using a named tunnel.\n- `WEBHOOK_SECRET` — HMAC secret for validating incoming webhook requests. Auto-generated on first run if not set.\n- `WEBHOOK_RETRY_DELAY` — Seconds between webhook registration retry attempts. Default: `60`.\n\n**Tunnel**\n\n- `TUNNEL_NAME` — Name of the Cloudflare named tunnel. Set during `claudio install`.\n- `TUNNEL_HOSTNAME` — Hostname for the named tunnel (e.g. `claudio.example.com`). Set during `claudio install`.\n\n\u003e Most of these variables are configured automatically by `claudio install` and `claudio telegram setup`. Manual editing is only needed for fine-tuning.\n\n---\n\n## Testing\n\nClaudio uses [BATS](https://github.com/bats-core/bats-core) (Bash Automated Testing System) for integration tests.\n\n```bash\n# Run all tests\nbats tests/\n\n# Run a specific test file\nbats tests/db.bats\n```\n\n---\n\n## Roadmap\n\n**Completed**\n\n- [x] Webhook signature validation\n- [x] Race conditions — Migrated from JSONL to SQLite\n- [x] Basic integration tests\n- [x] Input validation for model commands\n- [x] ShellCheck linting for scripts\n- [x] Cloudflared URL detection fails silently after 30 seconds\n- [x] Webhook health check cron job\n- [x] No retries with backoff for Telegram API\n- [x] Health check (`/health`) doesn't verify actual system state\n- [x] Auto-install dependencies (`sqlite3`, `jq`, `cloudflared`) during `claudio install`\n- [x] Show webhook registration failure reason instead of generic warning\n- [x] Add `claudio` to `$PATH` via symlink during install\n- [x] Environment variables documentation\n- [x] Image uploads\n\n**Future**\n\n- [ ] Support for editing messages and reactions\n- [ ] File uploads\n- [ ] Rate limiting\n- [ ] Voice messages from bot (TTS)\n- [ ] Voice messages from human (STT)\n- [ ] Support for group chats\n\n---\n\n## License\n\nClaudio is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.\n\n---\n\n## Contributing\n\nContributions are welcome! Please read the [CONTRIBUTING](CONTRIBUTING.md) file for details on how to contribute.\n\n---\n\n## Acknowledgments\n\nClaudio is built on top of [Claude](https://claude.ai/) and [Claude Code](https://claude.ai/code).\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedgarjs%2Fclaudio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedgarjs%2Fclaudio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedgarjs%2Fclaudio/lists"}