Full Stack Bootstrap

One-time bootstrap of the entire TTS + Telegram bot stack: Kokoro TTS engine (Apple Silicon MPS), Telegram bot via BotFather, secrets management, environment configuration, and shell symlinks.

Platform: macOS (Apple Silicon)

When to Use This Skill

• First-time setup of the tts-telegram-sync plugin
• Reinstalling after a clean OS install or hardware migration
• Setting up a new machine with the full TTS + Telegram stack
• Recovering from a broken installation (run kokoro-install.sh --uninstall first)

Requirements

Workflow Phases

Phase 0: Preflight Check

Verify all prerequisites are installed and accessible:

command -v bun    # Bun runtime for TypeScript bot
command -v mise   # Environment manager
command -v uv     # Python package manager
uv python list | grep 3.13  # Python 3.13 available

If any tool is missing, install via Homebrew (brew install <tool>). Python 3.13 is installed via uv python install 3.13.

Phase 1: Kokoro TTS Engine Install

Run the bundled installer script:

bash scripts/kokoro-install.sh --install

This performs:

1. Creates venv at ~/.local/share/kokoro/.venv with Python 3.13 via uv
2. Installs PyPI deps (kokoro, misaki, torch, soundfile, numpy, transformers, huggingface_hub, loguru) — versions pinned in scripts/kokoro-install.sh
3. Copies tts_generate.py from plugin bundle to ~/.local/share/kokoro/
4. Downloads Kokoro-82M model from HuggingFace (hexgrad/Kokoro-82M)
5. Verifies Apple Silicon MPS is available via torch.backends.mps.is_available()
6. Writes version.json with kokoro, torch, and Python versions

Phase 2: BotFather Token Setup

Guide the user through Telegram BotFather to create a bot token:

1. Open Telegram, search for @BotFather
2. Send /newbot, follow prompts (name + username)
3. Copy the HTTP API token
4. Verify token: curl -s "https://api.telegram.org/bot<TOKEN>/getMe" | jq .ok
5. Get chat_id by sending a message to the bot, then: curl -s "https://api.telegram.org/bot<TOKEN>/getUpdates" | jq '.result[0].message.chat.id'

If a token already exists at ~/.claude/.secrets/ccterrybot-telegram, verify it works and skip this phase.

Phase 3: Secrets Storage

Store the bot token securely:

mkdir -p ~/.claude/.secrets
chmod 700 ~/.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

Create .mise.local.toml (gitignored) in the bot directory to load secrets:

# ~/.claude/automation/claude-telegram-sync/.mise.local.toml
[env]
_.file = "{{env.HOME}}/.claude/.secrets/ccterrybot-telegram"

Phase 4: Environment Configuration

Add Kokoro paths to mise.toml:

# In ~/.claude/automation/claude-telegram-sync/mise.toml [env] section
KOKORO_VENV = "{{env.HOME}}/.local/share/kokoro/.venv"
KOKORO_SCRIPT = "{{env.HOME}}/.local/share/kokoro/tts_generate.py"

Phase 5: Shell Symlinks

Create symlinks in ~/.local/bin/ pointing to plugin shell scripts:

mkdir -p ~/.local/bin
ln -sf <plugin>/scripts/tts_kokoro.sh ~/.local/bin/tts_kokoro.sh
ln -sf <plugin>/scripts/tts_read_clipboard.sh ~/.local/bin/tts_read_clipboard.sh
ln -sf <plugin>/scripts/tts_read_clipboard_wrapper.sh ~/.local/bin/tts_read_clipboard_wrapper.sh
ln -sf <plugin>/scripts/tts_speed_up.sh ~/.local/bin/tts_speed_up.sh
ln -sf <plugin>/scripts/tts_speed_down.sh ~/.local/bin/tts_speed_down.sh
ln -sf <plugin>/scripts/tts_speed_reset.sh ~/.local/bin/tts_speed_reset.sh

Phase 6: Verification

1. Generate a test WAV and play it:

~/.local/share/kokoro/.venv/bin/python ~/.local/share/kokoro/tts_generate.py \
    --text "Hello, bootstrap complete." --voice af_heart --lang en-us --speed 1.0 --output /tmp/test-bootstrap.wav
afplay /tmp/test-bootstrap.wav
rm -f /tmp/test-bootstrap.wav

1. Verify bot responds to /status via Telegram API:

curl -s "https://api.telegram.org/bot${BOT_TOKEN}/getMe" | jq .ok

TodoWrite Task Templates

Template: Full Stack Bootstrap

1. [Preflight] Verify Bun installed
2. [Preflight] Verify mise installed
3. [Preflight] Verify uv installed
4. [Preflight] Verify Python 3.13 available via uv
5. [Kokoro] Run kokoro-install.sh --install
6. [Kokoro] Verify MPS acceleration
7. [BotFather] Guide BotFather token creation (or verify existing)
8. [Secrets] Store token in ~/.claude/.secrets/ccterrybot-telegram
9. [Secrets] Create .mise.local.toml with _.file reference to secrets
10. [Environment] Add KOKORO_VENV and KOKORO_SCRIPT to mise.toml
11. [Symlinks] Create ~/.local/bin/ symlinks for all TTS shell scripts
12. [Verify] Generate test WAV with Kokoro and play with afplay
13. [Verify] Check bot responds to /status via Telegram API

Post-Change Checklist

After modifying this skill:

1. Verify kokoro-install.sh --health passes all 8 checks
2. Confirm .mise.local.toml is gitignored
3. Test symlinks resolve correctly (ls -la ~/.local/bin/tts_*.sh)
4. Verify bot token works via getMe API call
5. Run a full TTS round-trip: clipboard text to audio playback
6. Update references/evolution-log.md with change description

Troubleshooting

Reference Documentation

• Kokoro Bootstrap – Detailed venv setup, Python 3.13 via uv, torch + MPS, model download
• BotFather Guide – Step-by-step Telegram bot creation and token management
• Upstream Fork – hexgrad/kokoro fork provenance and tts_generate.py bundling rationale
• Evolution Log – Change history for this skill