Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add terrylica/cc-skills --skill interactive-bot -a claude-code
Open on GitHub

What 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 getUpdates conflict when testing with production token
  • describe agent safety: mutex, timeout, circuit breaker

Example prompts for the agent

  • Open scripts/bot.ts and show where buildBot() initializes grammY
  • Where does the code handle the /compose command?
  • 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-code

2Manually: put the files in place

~/.claude/skills/interactive-bot/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/interactive-bot/

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

Similar skills

All skills for Telegram bots →

From the same set79

The whole set →
project-directory-migration project-directory-migration — a skill that transfers Claude Code sessions, history, and context when you rename or move a project folder. Runs interactively with dry-run preview and rollback support. CX Codex +1 119installs infra-deploy infra-deploy deploys self-hosted Cal.com to GCP Cloud Run on a Supabase PostgreSQL database, or runs it locally with Docker Compose. CX Codex +1 119installs email-triage email-triage sorts recent Gmail messages into three categories and ranks their urgency. Use it to request an email digest through the bot’s /digest command. CX Codex +1 117installs bot-process-control bot-process-control maintains process control rules for Gmail Commander bot instances in Restate and blocks duplicate Telegram pollers on workstations. CX Codex +1 117installs symmetric-dogfooding symmetric-dogfooding sets up bidirectional integration testing between two interdependent repositories before release without mocks. CX Codex +1 112installs calcom-access calcom-access is a Claude Code skill for five other platforms that gives the agent access to Cal.com API for bookings, event types, schedules and slot availability. The API key is read from 1Password via CALCOM_OP_UUID. CX Codex +1 107installs claude-code-proxy-patterns The claude-code-proxy-patterns skill covers proxy patterns for routing Claude Code models to different providers. Use it when setting up OAuth passthrough or investigating proxy authentication failures. CX Codex +1 106installs summarize summarize is a Claude Code skill that analyzes multi-gigabyte text files and session recordings step by step. It helps trace what happened when a file is too large to read normally. CX Codex +1 103installs

Project sponsors

Companies that keep this analytics open