\n\n
![\"Real-time](\"docs/images/working.jpg\")
\n\n\n\n_Tool calls stream in real time with a live status bar and cost tracking._\n\n
\n\n` with the 6-character pairing code\n\nTo pre-approve users on first run, set `TELEGRAM_ALLOWED_USERS` with comma-separated Telegram user IDs:\n\n```bash\nTELEGRAM_ALLOWED_USERS=783772449 claude-telegram-orchestrator\n```\n\n### Running as a daemon\n\nA built-in script sets up launchd (macOS) or systemd (Linux) automatically:\n\n```bash\nclaude-telegram-daemon install # install and start\nclaude-telegram-daemon status # check if running\nclaude-telegram-daemon logs # tail logs\nclaude-telegram-daemon uninstall # stop and remove\n```\n\nAuto-restarts on crash and starts on login. See the [orchestrator docs](docs/orchestrator-mode.md#running-as-a-daemon) for manual setup options.\n\n> [!TIP]\n> The **orchestrator mode** above is standalone and manages its own Claude sessions. There's also a [channel mode](docs/channel-mode.md) that attaches Telegram to an existing Claude Code session as an MCP plugin.\n\n## Features\n\n### Session management\nStart sessions in any project directory with a navigable file browser. Resume previous sessions by title. Run multiple sessions across different projects.\n\n### Real-time streaming\nTool calls, text output, and errors stream as separate messages with a live status bar showing the current step, tool count, and running cost.\n\n### Permission control\nPermission prompts are forwarded to Telegram with granular options — approve once, for the session, or always for the project. Switch between normal, plan, and auto-accept modes.\n\n### Slash command pass-through\nRun Claude Code commands directly: `/cc commit`, `/cc review-pr 123`, `/cc diff`. Or tap through an interactive menu.\n\n### Job scheduling\nSchedule prompts to run on a recurring or one-shot basis. Use natural syntax like `every 30m`, `at 9am weekdays`, or raw cron expressions. Claude can also self-schedule work via MCP tools — e.g. \"check the deploy every 5 minutes\" creates a job that outlives the session.\n\n## Commands\n\n| Command | What it does |\n|---|---|\n| `/new` | Start a session — shows a directory browser to pick your project |\n| `/resume` | Resume a previous session by title |\n| `/sessions` | List all sessions with tap-to-resume buttons |\n| `/cc` | Claude Code slash commands — menu or `/cc commit` directly |\n| `/mode` | Switch between normal / plan / auto-accept |\n| `/model` | Switch between sonnet / opus / haiku |\n| `/stop` | Stop current task or end session |\n| `/dirs` | Browse bookmarked and recent directories |\n| `/bookmark` | Save a directory shortcut: `/bookmark /path --name alias` |\n| `/schedule` | Schedule a job: `/schedule \"run tests\" every 30m` |\n| `/jobs` | List scheduled jobs with pause/cancel buttons |\n| `/cancel` | Cancel a scheduled job by ID |\n| `/pause` | Pause or resume a scheduled job |\n| `/cost` | Show session cost |\n| `/status` | Full session info |\n| `/help` | Show all commands |\n\nAnything that isn't a command is sent as a prompt to Claude.\n\n## Screenshots\n\n\n\n\n\n**Permission prompts** — approve once, for the session, or always for the project.\n\n \n\n\n**Directory browser** — navigate folders, bookmark shortcuts, tap to start.\n\n \n \n\n\n\n![\"Permission](\"docs/images/permissions.jpg\")
\n\n \n\n\n![\"Navigable](\"docs/images/new.jpg\")
\n\n \n \n\n\n\n**`/cc` command menu** — run slash commands and switch modes from the chat.\n\n \n\n\n**Session list** — auto-generated titles, tap to resume.\n\n \n \n\n\n\n![\"/cc](\"docs/images/cc.jpg\")
\n\n \n\n\n![\"Session](\"docs/images/sessions.jpg\")
\n\n \n \n
\n\n## Security\n\n- **Runs locally** — no cloud relay, no data leaves your machine, no inbound ports\n- **Pairing codes** — 6-character, 10-minute expiry, one-time use\n- **Allowlist** — only paired Telegram users can interact\n- **Permission relay** — HTTP server binds to `127.0.0.1` only\n- **Zero Telegram SDK** — native `fetch` only, minimal attack surface\n\n## Documentation\n\n| Doc | Contents |\n|---|---|\n| [Orchestrator Mode](docs/orchestrator-mode.md) | Setup, commands, permissions, streaming, sessions, env vars |\n| [Channel Mode](docs/channel-mode.md) | MCP channel plugin setup, pairing, access commands, tools |\n| [Architecture](docs/architecture.md) | System design, module map, security model, data flow |\n| [Changelog](CHANGELOG.md) | Release history |\n| [Contributing](CONTRIBUTING.md) | Development setup, code style, testing, pull requests |\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.\n\n## License\n\n[MIT](LICENSE)\n","readmeFilename":"README.md"}