bot-process-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)

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.

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

• Operational Commands - All start/stop/restart/status/logs commands
• Process Tree - Process hierarchy and bun --watch design rationale
• Evolution Log - Change history for this skill

Post-Execution Reflection

After this skill completes, reflect before closing the task:

0. 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.
1. What failed? — Fix the instruction that caused it. If it could recur, add it as an anti-pattern.
2. What worked better than expected? — Promote it to recommended practice. Document why.
3. What drifted? — Any script, reference, or external dependency that no longer matches reality gets fixed now.
4. 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.