Full Stack Bootstrap

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

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

• First-time setup of the tts-tg-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

brew install oven-sh/bun/bun

brew install mise

brew install uv

uv python install 3.13

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>

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. Requires Apple Silicon (fails fast on Intel/Linux)
2. Creates venv at

   ~/.local/share/kokoro/.venv

   with Python 3.13 via uv
3. Installs PyPI deps (mlx-audio, soundfile, numpy)
4. Copies

   kokoro_common.py

   and

   tts_generate.py

   from plugin bundle to

   ~/.local/share/kokoro/

5. Downloads Kokoro-82M-bf16 MLX model from HuggingFace (

   mlx-community/Kokoro-82M-bf16

   )
6. Writes

   version.json

   with mlx_audio version, backend, and model ID

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

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

# ~/.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/

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 MLX-Audio 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 6 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

brew install uv

uv python install 3.13

curl https://api.telegram.org/bot<TOKEN>/getMe

chmod +x scripts/kokoro-install.sh

kokoro-install.sh --uninstall

--install

scripts/tts_generate.py

Reference Documentation

• Kokoro Bootstrap - Detailed venv setup, Python 3.13 via uv, MLX-Audio, model download
• BotFather Guide - Step-by-step Telegram bot creation and token management
• Upstream Fork - MLX-Audio Kokoro upstream and bundled script 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.