interactive-bot — Claude Code skill: Telegram bot for Gmail
interactive-bot is a Claude Code skill that documents the Gmail Commander Telegram bot. It covers email slash commands, AI routing of free text through MCP, and compose/reply sessions.
MIT 114 installs ★ 3 updated 2026-10-25
npx skills add terrylica/cc-skills --skill interactive-bot -a claude-codeWhat interactive-bot does
Skill documents a Telegram bot that gives email access through commands /inbox, /search, /read, /compose, /reply and through free-text messages. Deterministic commands call Gmail CLI directly, free-text goes through an agent with four MCP tools. The bot runs on a private Restate tenant and imports buildBot() from scripts/bot.ts.
Inside: scripts/lib/commands.ts with command handlers, scripts/lib/agent-router.ts with MCP routing, scripts/lib/callbacks.ts with inline keyboards and session store, scripts/lib/telegram-format.ts with email rendering. Safety: mutex on concurrent agent queries, AGENT_TIMEOUT_MS timeout (2-minute default), circuit breaker disables the agent for 10 minutes after three failures in a row, skill contamination detection on agent responses.
Do not test scripts/bot.ts with the production token: Telegram allows one getUpdates poller per token, a second poller triggers 409 Conflict and breaks the deployed bot. Use a separate token for tests or import buildBot().
What it helps with
- explain how the Telegram bot for Gmail is built
- show where commands, MCP routing and keyboard handlers live
- warn about
getUpdatesconflict when testing with production token - describe agent safety: mutex, timeout, circuit breaker
Example prompts for the agent
- Open
scripts/bot.tsand show wherebuildBot()initializes grammY - Where does the code handle the
/composecommand? - Show how the agent router calls MCP tools in
scripts/lib/agent-router.ts
How to install interactive-bot
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill interactive-bot -a claude-code2Manually: put the files in place
~/.claude/skills/interactive-bot/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/interactive-bot/
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill interactive-bot -a codex2Manually: put the files in place
.agents/skills/interactive-bot/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill interactive-bot -a cursor2Manually: put the files in place
.cursor/skills/interactive-bot/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install terrylica/cc-skills plugins/gmail-commander/skills/interactive-bot2Manually: put the files in place
.github/skills/interactive-bot/SKILL.md1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill interactive-bot -a gemini-cli2Platform CLI
gemini skills install https://github.com/terrylica/cc-skills --path plugins/gmail-commander/skills/interactive-botManually: put the files in place
.devin/skills/interactive-bot/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill interactive-bot -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about interactive-bot
How to install interactive-bot in Claude Code?
Run npx skills add terrylica/cc-skills --skill interactive-bot -a claude-code, then open ~/.claude/skills/interactive-bot/SKILL.md.
What does interactive-bot do?
Skill documents the Gmail Commander Telegram bot: slash commands for inbox, search, compose, reply and AI routing of free-text through MCP.
Why can't I test scripts/bot.ts with the production token?
Telegram allows one getUpdates poller per token. A second poller triggers 409 Conflict and breaks the deployed bot.
Source text
SKILL.md · MIT
--- name: interactive-bot description: Gmail Commander Telegram bot - slash commands, inline keyboards, compose and reply flow, AI free-text routing. Built by buildBot() in this plugin and run by a private Restate deployment. TRIGGERS - telegram bot, bot commands, inbox bot allowed-tools: Read, Bash, Grep, Glob --- # Interactive Bot Gmail Commander Telegram bot — slash commands for email access + AI-powered free-text routing. This skill explains what the bot does and where its code lives; operating the running bot is covered by [bot-process-control](../bot-process-control/SKILL.md). > **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues. ## Where it runs The bot runs in a **private Restate tenant on an always-on Mac mini**. The tenant imports `buildBot()` from `scripts/bot.ts`, owns its own durable Telegram `getUpdates` chain, and feeds each update into the returned grammY bot through `bot.handleUpdate()`. There is no workstation daemon; the laptop launchd job was retired on 2026-09-24. Do **not** start `scripts/bot.ts` directly with the production bot token to "test" it. Telegram allows one `getUpdates` consumer per token, so a second poller breaks the deployed bot with `409 Conflict`. Test against a separate bot token, or exercise the code by importing `buildBot()`. ## Mandatory Preflight ### Step 1: Check the bot code exists and still exports `buildBot` ```bash PLUGIN="$HOME/.claude/plugins/marketplaces/cc-skills/plugins/gmail-commander" ls -la "$PLUGIN/scripts/bot.ts" 2>/dev/null || echo "SCRIPT_NOT_FOUND" grep -n "export async function buildBot" "$PLUGIN/scripts/bot.ts" || echo "buildBot EXPORT MISSING — the deployment depends on it" ``` ## Bot Commands (Sidebar Menu) | Command | Description | | -------- | --------------------------------------- | | /inbox | Show recent inbox emails | | /search | Search emails (Gmail query syntax) | | /read | Read email by ID | | /compose | Compose a new email | | /reply | Reply to an email | | /abort | Cancel current compose/reply action | | /drafts | List draft emails | | /digest | Triage the last N hours now (default 6) | | /status | Bot status and stats | | /help | Show all commands | ## Two-Tier Command System **Tier 1 — Deterministic**: Slash commands call the Gmail CLI directly (through `scripts/lib/gmail-client.ts`, which runs the binary named by `GMAIL_CLI_BIN`). **Tier 2 — Intelligent**: Free-text messages route through the Agent SDK (`HAIKU_MODEL`) with 4 Gmail MCP tools (list, search, read, draft). ## Safety Controls - **Mutex**: 1 agent query at a time - **Timeout**: `AGENT_TIMEOUT_MS` per query (2-minute default) - **Circuit Breaker**: 3 failures in a row disables the agent for 10 minutes - **Anti-contamination**: Skill contamination detection on all agent responses - **Auth Guard**: Only responds to the authorized `TELEGRAM_CHAT_ID` ## Source Map | Concern | File | | ---------------------------------------- | ------------------------------------------------------------------------ | | Wiring, compose/reply session flow | [`scripts/bot.ts`](../../scripts/bot.ts) (`buildBot()`) | | Command list and handlers | [`scripts/lib/commands.ts`](../../scripts/lib/commands.ts) | | Inline-keyboard callbacks, session store | [`scripts/lib/callbacks.ts`](../../scripts/lib/callbacks.ts) | | Free-text routing, MCP tools | [`scripts/lib/agent-router.ts`](../../scripts/lib/agent-router.ts) | | Email rendering, HTML escaping | [`scripts/lib/telegram-format.ts`](../../scripts/lib/telegram-format.ts) | | Message chunking (4096-char limit) | [`scripts/lib/telegram-chunk.ts`](../../scripts/lib/telegram-chunk.ts) | ## Post-Change Checklist - [ ] YAML frontmatter valid (no colons in description) - [ ] Trigger keywords current - [ ] Path patterns use $HOME not hardcoded paths - [ ] `buildBot()` still starts no transport and takes no PID lock on import ## Post-Execution Reflection After this skill completes, reflect before closing the task: 0. **Locate yourself.** — Find this SKILL.md's canonical path before editing. 1. **What failed?** — Fix the instruction that caused it. 2. **What worked better than expected?** — Promote to recommended practice. 3. **What drifted?** — Fix any script, reference, or dependency that no longer matches reality. 4. **Log it.** — Evolution-log entry with trigger, fix, and evidence. Do NOT defer. The next invocation inherits whatever you leave behind.
© terrylica · MIT · terrylica/cc-skills