Agent-Skills.md

Agent Skills: Bot Process Control

Gmail Commander daemon lifecycle - start, stop, restart, status, logs, launchd plist management. TRIGGERS - bot start, bot stop, bot restart, bot status, bot logs, launchd, daemon, process control, gmail-commander service.

UncategorizedID: terrylica/cc-skills/bot-process-control

Repository

terrylica/cc-skills
terrylicaLicense: MIT
264

Install this agent skill to your local

pnpm dlx add-skill https://github.com/terrylica/cc-skills/tree/HEAD/plugins/tts-tg-sync/skills/bot-process-control

Skill Files

Browse the full folder contents for bot-process-control.

Download Skill

Loading file tree…

plugins/tts-tg-sync/skills/bot-process-control/SKILL.md

Skill Metadata

Name
bot-process-control
Description
Start, stop, or restart the Telegram sync bot process. TRIGGERS - start bot, stop bot, restart bot, bot process, bot status, bot control.

Bot Process Control

Start, stop, restart, and monitor the Telegram sync bot process. Provides lifecycle management for the bun --watch bot runner with process verification and log access.

Platform: macOS (Apple Silicon)

When to Use This Skill

  • Start or restart the Telegram bot after configuration changes
  • Stop the bot before maintenance or debugging
  • Check whether the bot is running and healthy
  • Tail recent bot logs to diagnose issues
  • Recover from multiple-instance or zombie process scenarios

Requirements

  • Bun runtime installed via mise
  • Bot source at ~/.claude/automation/claude-telegram-sync/
  • Secrets file at ~/.claude/.secrets/ccterrybot-telegram
  • mise.toml configured in the bot source directory

Workflow Phases

Phase 1: Status Check

Show current bot process state using pgrep:

pgrep -la 'bun.*src/main.ts'

If no output, the bot is not running. If multiple lines appear, there are duplicate instances that need cleanup.

Phase 2: Ask User Intent

Use AskUserQuestion to determine the desired action:

  • start - Launch the bot in background with bun --watch
  • stop - Kill the bot process cleanly
  • restart - Stop then start
  • logs - Tail recent log output

Phase 3: Execute Action

In production, launchd manages the bot via a compiled Swift runner binary. The runner uses bun --watch, so code changes auto-restart the service.

Restart (production — kill bun, Swift runner respawns it):

pkill -f 'bun.*src/main.ts'
sleep 2
pgrep -la 'bun.*src/main.ts'

Stop (full — kills both runner and bun):

pkill -f 'telegram-bot-runner'
pkill -f 'bun.*src/main.ts'

Start (production — via launchd):

launchctl kickstart -k gui/$(id -u)/com.terryli.telegram-bot

Start (ad-hoc — shell session, for debugging):

cd ~/.claude/automation/claude-telegram-sync && bun --watch run src/main.ts >> /private/tmp/telegram-bot.log 2>&1 &

Logs:

tail -50 /private/tmp/telegram-bot.log
# Or structured logs:
tail -50 ~/.local/state/launchd-logs/telegram-bot/stderr.log

Phase 4: Verify

Confirm the process state changed as expected:

pgrep -la 'bun.*src/main.ts'

TodoWrite Task Templates

1. [Check] Show current bot process status with pgrep
2. [Action] Present start/stop/restart/logs options via AskUserQuestion
3. [Execute] Run the selected action command
4. [Verify] Confirm process state changed as expected
5. [Logs] Optionally tail recent logs for confirmation
6. [Done] Report final process status to user

Post-Execution Reflection

After this skill completes, reflect before closing the task:

  1. Locate yourself. — Find this SKILL.md's canonical path (Glob for this skill's name) before editing. All corrections target THIS file and its sibling references/ — never other documentation.
  2. What failed? — Fix the instruction that caused it. If it could recur, add it as an anti-pattern.
  3. What worked better than expected? — Promote it to recommended practice. Document why.
  4. What drifted? — Any script, reference, or external dependency that no longer matches reality gets fixed now.
  5. Log it. — Every change gets an evolution-log entry with trigger, fix, and evidence.

Do NOT defer. The next invocation inherits whatever you leave behind.

Post-Change Checklist

  • [ ] Verified no duplicate bot instances running
  • [ ] Confirmed bot responds to Telegram messages (if started)
  • [ ] Checked log output for startup errors (if started)
  • [ ] Ensured previous process fully terminated (if stopped/restarted)

Troubleshooting

| Issue | Cause | Solution | | ---------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------- | | Bot not running | Process crashed or was never started | Check with pgrep, runner should auto-respawn; if runner also dead, launchctl kickstart | | Multiple instances | Previous stop did not fully terminate | pkill -f 'telegram-bot-runner'; pkill -f 'bun.*src/main.ts', then restart via launchd | | Code changes not picked up | Bot started without --watch | Kill bun process — runner respawns with --watch; or recompile runner if it's outdated | | --watch not reloading | File outside watch scope changed | bun --watch monitors the entry file's dependency tree; config-only changes (mise.toml) need a kill | | Logs not writing | Log directory missing or permissions | Verify ~/.local/state/launchd-logs/telegram-bot/ exists and is writable | | bun not found | mise shims not in PATH | Runner sets PATH explicitly; recompile runner if shims path changed | | Bot starts but crashes immediately | Missing env vars or secrets | Check ~/.claude/.secrets/ccterrybot-telegram exists; verify mise.toml env section |

Reference Documentation