# Setup

> One-time bootstrap for Kokoro TTS, Telegram bot, and BotFather setup. TRIGGERS - tts setup, kokoro install, telegram bot setup

- Skill: `terrylica/setup-3` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add terrylica/setup-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/terrylica/setup-3/raw
- Safety review: pending (external: skill-scanner WARNING, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: terrylica (https://skillmd.com/u/terrylica)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/terrylica/setup-3

---


> **Prerequisite — `cc-plugin-root`.** This skill resolves its scripts with `cc-plugin-root <plugin>`
> (the `CLAUDE_PLUGIN_ROOT` placeholder is not a shell variable and expands to empty). If the command is missing, run
> `/itp:setup` (its first step installs it), or link it directly:
>
> ```bash
> mkdir -p ~/.local/bin && ln -sfn \
>   ~/.claude/plugins/marketplaces/cc-skills/scripts/cc-plugin-root ~/.local/bin/cc-plugin-root
> ```

# 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.14 | Yes      | `uv run --python 3.14 python --version` |
| Homebrew    | Yes      | `brew --version`                        |

## Workflow

### Step 1: Preflight

```bash
/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:

```bash
PLUGIN_DIR="$(cc-plugin-root tts-tg-sync)"
bash "$PLUGIN_DIR/scripts/kokoro-install.sh" --install
```

This creates a Python 3.14 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:

```bash
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:

```bash
PLUGIN_DIR="$(cc-plugin-root 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

```bash
# Test Kokoro health
PLUGIN_DIR="$(cc-plugin-root 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.