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)

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

Component Required Installation

Bun Yes brew install oven-sh/bun/bun

mise Yes brew install mise

uv Yes brew install uv

Python 3.13 Yes uv python install 3.13

Homebrew Yes Already installed on macOS dev machines

Apple Silicon (M1+) Yes Required for MLX Metal acceleration

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:

• Requires Apple Silicon (fails fast on Intel/Linux)

• Creates venv at ~/.local/share/kokoro/.venv with Python 3.13 via uv

• Installs PyPI deps (mlx-audio, soundfile, numpy)

• Copies kokoro_common.py and tts_generate.py from plugin bundle to ~/.local/share/kokoro/

• Downloads Kokoro-82M-bf16 MLX model from HuggingFace (mlx-community/Kokoro-82M-bf16 )

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

• Open Telegram, search for @BotFather

• Send /newbot , follow prompts (name + username)

• Copy the HTTP API token

• Verify token: curl -s "https://api.telegram.org/bot&#x3C;TOKEN>/getMe" | jq .ok

• Get chat_id by sending a message to the bot, then: curl -s "https://api.telegram.org/bot&#x3C;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

• 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

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

• Verify kokoro-install.sh --health passes all 6 checks

• Confirm .mise.local.toml is gitignored

• Test symlinks resolve correctly (ls -la ~/.local/bin/tts_*.sh )

• Verify bot token works via getMe API call

• Run a full TTS round-trip: clipboard text to audio playback

• Update references/evolution-log.md with change description

Troubleshooting

Issue Cause Solution

uv not found Not installed brew install uv

Python 3.13 not available Not installed via uv uv python install 3.13

Not Apple Silicon Intel Mac or Linux Requires M1 or newer Mac (MLX Metal)

Model download fails Network issue or HuggingFace outage Check internet connectivity, retry

BotFather token invalid Typo or revoked token Verify via curl https://api.telegram.org/bot&#x3C;TOKEN>/getMe

kokoro-install.sh permission denied Script not executable chmod +x scripts/kokoro-install.sh

Venv already exists Previous partial install Run kokoro-install.sh --uninstall then --install

tts_generate.py not found Bundle copy failed Check scripts/tts_generate.py exists in plugin

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