Full Stack Bootstrap

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

---

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.14  # Python 3.14 available

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

Phase 1: Kokoro TTS Engine Install

Run the bundled installer script:

bash scripts/kokoro-install.sh --install

<!-- SSoT-OK: kokoro-install.sh is the SSoT for versions and deps -->

This performs:

1. Requires Apple Silicon (fails fast on Intel/Linux) 2. Creates venv at ~/.local/share/kokoro/.venv with Python 3.14 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, 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.14 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

---

Reference Documentation

• Kokoro Bootstrap - Detailed venv setup, Python 3.14 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.

---

---

BotFather Guide

Step-by-step guide for creating a Telegram bot via BotFather and managing its credentials.

Creating a New Bot

Step 1: Open BotFather

1. Open Telegram (desktop or mobile) 2. Search for @BotFather (verified blue checkmark) 3. Start a conversation with /start

Step 2: Create the Bot

1. Send /newbot 2. BotFather asks: "Alright, a new bot. How are we going to call it?" 3. Enter a display name (e.g., Claude Code Terry Bot) 4. BotFather asks: "Good. Now let's choose a username for your bot." 5. Enter a username ending in bot (e.g., ccterrybot) 6. BotFather responds with the HTTP API token

Step 3: Copy the Token

The token looks like: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz

Never share this token publicly. It provides full control over the bot.

Step 4: Verify the Token

curl -s "https://api.telegram.org/bot<TOKEN>/getMe" | jq .

Expected response:

{
  "ok": true,
  "result": {
    "id": 123456789,
    "is_bot": true,
    "first_name": "Claude Code Terry Bot",
    "username": "ccterrybot"
  }
}

Getting Your chat_id

The bot needs your chat_id to send messages to you directly.

Step 1: Send a Message to the Bot

Open your bot in Telegram and send any message (e.g., /start or hello).

Step 2: Retrieve the chat_id

curl -s "https://api.telegram.org/bot<TOKEN>/getUpdates" | jq '.result[0].message.chat.id'

This returns your numeric chat ID (e.g., 987654321).

Storing Credentials

Secrets File

Store both BOT_TOKEN and CHAT_ID in the secrets file:

mkdir -p ~/.claude/.secrets
chmod 700 ~/.claude/.secrets

cat > ~/.claude/.secrets/ccterrybot-telegram << 'EOF'
BOT_TOKEN=<your-bot-token>
CHAT_ID=<your-chat-id>
EOF

chmod 600 ~/.claude/.secrets/ccterrybot-telegram

mise Integration

The bot's .mise.local.toml (gitignored) loads the secrets file:

[env]
_.file = "{{env.HOME}}/.claude/.secrets/ccterrybot-telegram"

This makes BOT_TOKEN and CHAT_ID available as environment variables when mise is activated in the bot directory.

Managing the Bot

Useful BotFather Commands

Revoking a Compromised Token

If the token is leaked:

1. Open @BotFather 2. Send /revoke 3. Select the bot 4. BotFather generates a new token 5. Update ~/.claude/.secrets/ccterrybot-telegram with the new token 6. Restart the bot process

Verifying an Existing Token

If a token already exists at ~/.claude/.secrets/ccterrybot-telegram:

# Source the secrets file
source ~/.claude/.secrets/ccterrybot-telegram

# Verify token is valid
curl -s "https://api.telegram.org/bot${BOT_TOKEN}/getMe" | jq '.ok'
# Expected: true

# Verify chat_id receives messages
curl -s -X POST "https://api.telegram.org/bot${BOT_TOKEN}/sendMessage" \
    -d "chat_id=${CHAT_ID}" \
    -d "text=Bootstrap verification" | jq '.ok'
# Expected: true

If both return true, skip the BotFather setup phase.

full-stack-bootstrap Evolution Log

Kokoro TTS Engine Bootstrap Reference

Detailed reference for the Kokoro TTS engine installation managed by scripts/kokoro-install.sh.

Architecture

~/.local/share/kokoro/          # XDG-compliant install directory
├── .venv/                      # Python 3.14 venv (created by uv)
│   └── bin/python              # Venv Python interpreter
├── kokoro_common.py            # Shared constants and synthesis core (SSoT)
├── tts_generate.py             # CLI script (copied from plugin bundle)
└── version.json                # Installation metadata

Model cache is stored separately at ~/.cache/huggingface/hub/models--mlx-community--Kokoro-82M-bf16/ (HuggingFace default).

Python 3.14 via uv

<!-- SSoT-OK: kokoro-install.sh is the SSoT for the actual version pin -->

The installer uses uv venv --python 3.14 to create the virtual environment. This ensures:

• Python 3.14 is used consistently (per the global Python version policy)
• uv handles Python discovery and download if needed
• The venv is isolated from system Python

If Python 3.14 is not available, install it first:

uv python install 3.14

PyPI Dependencies

All dependency versions are managed by scripts/kokoro-install.sh (the SSoT). Key packages:

MLX-Audio Verification

The installer verifies MLX-Audio availability:

from mlx_audio.tts.utils import load_model
print("MLX-Audio OK")

MLX-Audio provides Metal-accelerated inference on Apple Silicon. The installer requires uname -m == arm64 and fails fast on Intel or Linux.

Model Download

The Kokoro-82M MLX model is downloaded from HuggingFace on first use:

from mlx_audio.tts.utils import load_model
load_model("mlx-community/Kokoro-82M-bf16")

This triggers an automatic download to ~/.cache/huggingface/hub/. Subsequent runs use the cached model.

version.json

The installer writes a metadata file tracking the installation:

{
  "mlx_audio": "<version>",
  "backend": "mlx",
  "python": "3.14",
  "model": "mlx-community/Kokoro-82M-bf16",
  "installed_at": "2026-02-28T00:00:00Z",
  "source": "kokoro-install.sh --install",
  "venv_path": "~/.local/share/kokoro/.venv"
}

This is used by --health checks and upgrade tracking.

Installer Commands

Health Check Details

kokoro-install.sh --health runs 6 checks:

1. Venv exists at ~/.local/share/kokoro/.venv 2. Python 3.14 executable is present 3. mlx_audio package is importable 4. kokoro_common.py exists 5. tts_generate.py exists 6. version.json exists

Upstream: MLX-Audio Kokoro

Reference for the relationship between the MLX-Audio project and the bundled TTS scripts.

Upstream Project

• Repository: Blaizzy/mlx-audio
• PyPI package: mlx-audio (PyPI)
• Model: Kokoro-82M-bf16 (hosted on HuggingFace at mlx-community/Kokoro-82M-bf16)

Why We Bundle Scripts

The bundled scripts (kokoro_common.py, tts_generate.py) are custom CLI wrappers we maintain. They are not part of the mlx-audio PyPI package.

Rationale

1. mlx-audio provides the load_model / generate Python API but no standalone CLI suited for shell script integration 2. kokoro_common.py is our SSoT for model ID, sample rate, language aliases, and synthesis loop 3. tts_generate.py is our CLI adapter that wraps kokoro_common for shell script integration 4. The scripts add features not in the upstream library:

• Chunked streaming mode (--chunk flag) for progressive playback
• Text sanitization (surrogate removal, control char stripping)
• Hierarchical text chunking (paragraph, sentence, word boundaries)

File Flow

scripts/kokoro_common.py     (plugin bundle - SSoT for synthesis core)
scripts/tts_generate.py      (plugin bundle - SSoT for CLI)
        │
        ├── kokoro-install.sh --install  (copies to runtime directory)
        │
        └── ~/.local/share/kokoro/       (runtime location)
              ├── kokoro_common.py
              └── tts_generate.py

The installer (kokoro-install.sh) copies the bundled scripts to the Kokoro directory during --install and --upgrade operations.

Dependency Relationship

PyPI mlx-audio package (upstream library)
    └── provides load_model + generate API
         └── kokoro_common.py (our synthesis SSoT)
              └── tts_generate.py (our CLI wrapper)
                   └── tts_kokoro.sh (shell script, calls tts_generate.py)
                        └── Bot TTS integration (TypeScript, spawns shell script)

Upgrade Considerations

When upgrading the mlx-audio package:

1. Check the Blaizzy/mlx-audio releases for breaking changes 2. Run kokoro-install.sh --upgrade to update all deps 3. The upgrade re-copies bundled scripts from the plugin bundle 4. Run kokoro-install.sh --health to verify everything works 5. Test TTS output quality with tts_kokoro_audition.sh

Model Details

• Name: Kokoro-82M-bf16
• Format: MLX (bfloat16 quantized)
• Cache location: ~/.cache/huggingface/hub/models--mlx-community--Kokoro-82M-bf16/
• Sample rate: 24000 Hz
• Output format: WAV (via soundfile)

The model is downloaded automatically on first use via huggingface_hub. Subsequent runs use the cached version. The --uninstall command preserves the model cache (only removes venv and scripts).