Cc-skills bot-process-control

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

install

source · Clone the upstream repo

git clone https://github.com/terrylica/cc-skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/terrylica/cc-skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/plugins/tts-tg-sync/skills/bot-process-control" ~/.claude/skills/terrylica-cc-skills-bot-process-control-7c67ba && rm -rf "$T"

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

source content

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:

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.
What failed? — Fix the instruction that caused it. If it could recur, add it as an anti-pattern.
What worked better than expected? — Promote it to recommended practice. Document why.
What drifted? — Any script, reference, or external dependency that no longer matches reality gets fixed now.
Log it. — Every change gets an evolution-log entry with trigger, fix, and evidence.