Skip to main content
skill CX Codex

bot-process-control — Claude Code skill: what it does, how to install

bot-process-control maintains process control rules for Gmail Commander bot instances in Restate and blocks duplicate Telegram pollers on workstations.

MIT 117 installs ★ 3 updated 2026-10-25

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

What bot-process-control does

This skill outlines operational boundaries for Gmail Commander components: GmailBot, GmailBotChat, GmailDigest, and GmailAuth. The workloads run unattended inside a private Restate tenant on an always-on Mac mini. Local workstation launchd jobs were retired on 2026-09-24, so operational tasks belong strictly in the private repository runbook.

Executing scripts/bot.ts locally with production credentials forces Telegram to return 409 Conflict, immediately breaking message intake for both instances. To protect availability, the skill provides read-only inspection commands with launchctl and pgrep, directing users to confirm health by sending /status directly to the bot in Telegram.

What it helps with

  • prevent duplicate Telegram pollers from colliding on the same bot token
  • verify that retired workstation launchd jobs are not running
  • inspect bot responsiveness via the /status Telegram command
  • identify invalid_grant token failures triggered by GmailAuth

Example prompts for the agent

  • Check gmail bot down status and make sure no local pollers are active
  • Run the mandatory preflight check for gmail-commander processes
  • Confirm whether GmailBotChat is processing incoming messages

How to install bot-process-control

1Skills CLI (Vercel)

npx skills add terrylica/cc-skills --skill bot-process-control -a claude-code

2Manually: put the files in place

~/.claude/skills/bot-process-control/SKILL.md

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

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about bot-process-control

How to install bot-process-control in Claude Code?

Run npx skills add terrylica/cc-skills --skill bot-process-control -a claude-code. The skill definition will be placed into ~/.claude/skills/bot-process-control/SKILL.md.

What does bot-process-control do?

It guides safe inspection of Gmail Commander services in Restate while stopping accidental local execution of bot polling scripts.

Why is running scripts/bot.ts locally forbidden with production tokens?

Telegram permits exactly one active getUpdates consumer per token. A second consumer triggers HTTP 409 Conflict, degrades bot polling, and alerts the on-call operator.

Source text

SKILL.md · MIT
---
name: bot-process-control
description: Gmail Commander bot and digest process control - they run unattended in a private Restate deployment, never as workstation launchd jobs. Where they run, how to check them, what not to start locally. TRIGGERS - bot start, bot stop, bot restart, bot status, gmail bot down
allowed-tools: Read, Bash, Grep, Glob
---

# Bot Process Control

Where the Gmail Commander bot and scheduled digest run, how to tell whether they are healthy, and what must never be started on a workstation.

> **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 the processes live

Neither process runs on a workstation. Both run in a **private Restate tenant on an always-on Mac mini**, deployed from a private repository:

| Service        | Role                                                                                                |
| -------------- | --------------------------------------------------------------------------------------------------- |
| `GmailBot`     | Owns the Telegram `getUpdates` chain (one durable, self-re-arming poll) and dispatches each update  |
| `GmailBotChat` | Runs one update through the grammY bot built by this plugin's `buildBot()`, in per-chat order       |
| `GmailDigest`  | Scheduled email digest to Telegram, several times a day (its own implementation, not this plugin's) |
| `GmailAuth`    | Mints Gmail access tokens on demand from a refresh token held in the deployment's secret store      |

**Starting, stopping, restarting, deploying, reading logs, rotating secrets and OAuth re-consent are all done through that repository's runbook.** This public skill intentionally carries no host names, deploy commands or credential paths for it. If you do not have access to that repository, stop and ask the operator.

The laptop launchd jobs `com.example.gmail-commander-bot` and `com.example.gmail-commander-digest` were **retired on 2026-09-24**. Do not recreate their plists, launcher scripts or env files.

## Mandatory Preflight

### Step 1: Confirm nothing is running locally (read-only)

```bash
echo "=== Local gmail-commander launchd jobs (expected: none) ==="
launchctl list | grep -F gmail-commander || echo "none"

echo ""
echo "=== Local gmail-commander plists (expected: none) ==="
ls ~/Library/LaunchAgents 2>/dev/null | grep -F gmail-commander || echo "none"

echo ""
echo "=== Local standalone bot process (expected: none) ==="
pgrep -fl "gmail-commander/scripts/bot.ts" || echo "none"
```

If any of these finds something, **report it to the operator instead of loading, unloading or killing it yourself**: a live local poller competes with the tenant for the same bot token.

### Step 2: Check the deployed bot from the user's side

The one check that needs no deployment access: send `/status` to the bot in its Telegram chat. A reply with uptime and counters means `GmailBotChat` is handling updates. No reply within a minute means the poll chain or the tenant is down — escalate through the runbook.

## Never start a second poller

`scripts/bot.ts` still has a standalone long-polling `main()`, guarded by `import.meta.main` so that importing `buildBot()` never polls. **Do not run it with the production bot token.** Telegram allows exactly one `getUpdates` consumer per token; a second one makes Telegram answer `409 Conflict` and both pollers become unreliable, and the tenant pages the operator when it sees that conflict.

The standalone entry point exists for other installations of this public plugin, with their own bot token. It takes a PID lock at `/tmp/gmail-commander-bot.pid` and reads the variables listed in the [plugin CLAUDE.md](../../CLAUDE.md#environment-variables). This plugin no longer ships process-supervisor templates for it.

## Telegram Commands

| 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                       |

> **Note**: `/abort` cancels any in-progress compose or reply session. Works at any step in the flow.

## OAuth failures in the deployment

When Google rejects the deployment's refresh token (`invalid_grant`), `GmailAuth` pages the operator. Recovery needs a browser consent on a workstation and a secret update in the deployment, both described in the private runbook. The CLI's own `invalid_grant` recovery on a workstation is a different token and is covered in [gmail-access](../gmail-access/SKILL.md#diagnosing-invalid_grant).

## Post-Change Checklist

- [ ] YAML frontmatter valid (no colons in description)
- [ ] Trigger keywords current
- [ ] Path patterns use $HOME not hardcoded paths
- [ ] No launchd templates, host names or credential paths reintroduced
- [ ] `buildBot()` contract in the plugin CLAUDE.md still matches `scripts/bot.ts`

## 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 DevOps and infrastructure →

From the same set79

The whole set →
distributed-job-safety The distributed-job-safety skill helps prevent file collisions and unsafe concurrency in pipelines using pueue, moon, and systemd-run. Use it when jobs share files or compete for host resources. CX Codex +1 120installs 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 interactive-bot 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. CX Codex +1 114installs 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

More in the catalog

Project sponsors

Companies that keep this analytics open