TTS Telegram Sync Setup

Full-stack bootstrap: Kokoro TTS engine, Telegram bot, BotFather token, secrets, symlinks.

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.

Prerequisites

Component	Required	Check
Bun	Yes	bun --version
mise	Yes	mise --version
uv	Yes	uv --version
Python 3.13	Yes	uv run --python 3.13 python --version
Homebrew	Yes	brew --version

Workflow

Step 1: Preflight

/usr/bin/env bash << 'PREFLIGHT_EOF'
echo "=== TTS Telegram Sync Preflight ==="
for cmd in bun mise uv brew; do
    if command -v "$cmd" &>/dev/null; then
        echo "  [OK] $cmd: $($cmd --version 2>&1 | head -1)"
    else
        echo "  [FAIL] $cmd not found"
    fi
done
PREFLIGHT_EOF

Step 2: Kokoro Install

Run the Kokoro TTS engine installer:

PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/marketplaces/cc-skills/plugins/tts-tg-sync}"
bash "$PLUGIN_DIR/scripts/kokoro-install.sh" --install

This creates a Python 3.13 venv at ~/.local/share/kokoro/, installs MLX-Audio deps, downloads the Kokoro-82M-bf16 MLX model, and verifies MLX Metal acceleration.

Step 3: BotFather Token

Guide the user through Telegram BotFather setup:

1. Open Telegram, search for @BotFather
2. Send /newbot (or verify existing bot with /mybots)
3. Copy the bot token
4. Store in secrets file:

mkdir -p ~/.claude/.secrets
echo "BOT_TOKEN=<token>" > ~/.claude/.secrets/ccterrybot-telegram
echo "CHAT_ID=<chat_id>" >> ~/.claude/.secrets/ccterrybot-telegram
chmod 600 ~/.claude/.secrets/ccterrybot-telegram

Use AskUserQuestion to ask if user has an existing bot token or needs to create one.

Step 4: Symlinks

Create symlinks in ~/.local/bin/ for all TTS shell scripts:

PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/marketplaces/cc-skills/plugins/tts-tg-sync}"
mkdir -p ~/.local/bin
for script in tts_kokoro.sh tts_kokoro_audition.sh tts_read_clipboard.sh tts_read_clipboard_wrapper.sh tts_speed_up.sh tts_speed_down.sh tts_speed_reset.sh; do
    ln -sf "$PLUGIN_DIR/scripts/$script" ~/.local/bin/"$script"
done

Step 5: Verify

# Test Kokoro health
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/marketplaces/cc-skills/plugins/tts-tg-sync}"
bash "$PLUGIN_DIR/scripts/kokoro-install.sh" --health

# Test bot connectivity
source ~/.claude/.secrets/ccterrybot-telegram
curl -s "https://api.telegram.org/bot${BOT_TOKEN}/getMe" | jq .ok

Troubleshooting

Issue	Cause	Solution
uv not found	Not installed	brew install uv
Not Apple Silicon	Intel Mac or Linux	Requires M1+ Mac (MLX Metal)
Model download slow	Large first download	~400MB, wait for completion
Token invalid	Typo or expired	Re-verify with /mybots in BotFather
Symlinks broken	Plugin path changed	Re-run symlink creation step

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.