Diagnose and resolve TTS and Telegram bot issues. TRIGGERS - tts not working, bot not responding, kokoro error, audio not playing, lock stuck, telegram bot troubleshoot, diagnose issue.
From tts-tg-syncnpx claudepluginhub terrylica/cc-skills --plugin tts-tg-syncThis skill is limited to using the following tools:
references/common-issues.mdreferences/evolution-log.mdreferences/lock-debugging.mdGuides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Migrates code, prompts, and API calls from Claude Sonnet 4.0/4.5 or Opus 4.1 to Opus 4.5, updating model strings on Anthropic, AWS, GCP, Azure platforms.
Optimizes cloud costs on AWS, Azure, GCP via rightsizing, tagging strategies, reserved instances, spot usage, and spending analysis. Use for expense reduction and governance.
Diagnose and fix common TTS + Telegram bot issues through systematic symptom collection, automated diagnostics, and targeted fixes.
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.
~/.claude/automation/claude-telegram-sync/ (bot source)~/.local/share/kokoro/ (Kokoro engine)~/.local/state/launchd-logs/telegram-bot/ (launchd logs)~/.claude/automation/claude-telegram-sync/logs/audit/ (NDJSON audit)| Issue | Likely Cause | Diagnostic | Fix |
|---|---|---|---|
| No audio output | Stale TTS lock | stat /tmp/kokoro-tts.lock | rm -f /tmp/kokoro-tts.lock |
| Bot not responding | Process crashed | pgrep -la 'bun.*src/main.ts' | Restart: cd ~/.claude/automation/claude-telegram-sync && bun --watch run src/main.ts |
| Kokoro timeout | First-run model load | Check ~/.cache/huggingface/ | Wait for download, or re-run kokoro-install.sh --install |
| Queue full | Rapid-fire notifications | Check queue depth in audit log | Increase TTS_MAX_QUEUE_DEPTH in mise.toml or drain queue |
| Lock stuck forever | Heartbeat process died | stat /tmp/kokoro-tts.lock + pgrep -x afplay | If lock stale >30s AND no audio process, rm lock |
| Slow MLX acceleration | Wrong Python or deps | python -c "from mlx_audio.tts.utils import load_model; print('MLX OK')" | Reinstall via kokoro-install.sh --upgrade |
| Double audio playback | Lock race condition | Check for multiple afplay processes | Kill all: pkill -x afplay, then restart |
Use AskUserQuestion to understand what the user is experiencing. Key questions:
Based on symptoms, run the relevant subset of these checks:
# Lock state
ls -la /tmp/kokoro-tts.lock 2>/dev/null && stat -f "%Sm" /tmp/kokoro-tts.lock || echo "No lock file"
# Audio processes
pgrep -la afplay; pgrep -la say
# Bot process
pgrep -la 'bun.*src/main.ts'
# Kokoro health
~/.local/share/kokoro/.venv/bin/python -c "from mlx_audio.tts.utils import load_model; print('MLX-Audio OK')"
# Recent errors in audit log
tail -20 ~/.claude/automation/claude-telegram-sync/logs/audit/*.ndjson 2>/dev/null | grep -i error
# Recent bot console output
tail -50 /private/tmp/telegram-bot.log 2>/dev/null | grep -i -E '(error|fail|timeout)'
Map diagnostic output to the Known Issue Table above. Common patterns:
from mlx_audio.tts.utils import load_model fails = MLX-Audio brokenApply the targeted fix from the Known Issue Table. Always use the least disruptive fix first.
After applying the fix, verify the issue is resolved:
# Quick TTS test
~/.local/share/kokoro/.venv/bin/python ~/.local/share/kokoro/tts_generate.py \
--text "Diagnostic test complete" --voice af_heart --lang en-us --speed 1.0 \
--output /tmp/kokoro-tts-diag-test.wav && afplay /tmp/kokoro-tts-diag-test.wav && echo "OK"
# Full health check
~/eon/cc-skills/plugins/tts-tg-sync/scripts/kokoro-install.sh --health
1. [Symptoms] Collect symptoms via AskUserQuestion
2. [Triage] Map symptoms to likely causes
3. [Lock] Check TTS lock state (mtime, PID, stale detection)
4. [Process] Check bot process and audio processes
5. [Kokoro] Verify Kokoro venv and MLX-Audio availability
6. [Logs] Check recent audit logs for errors
7. [Fix] Apply targeted fix for identified root cause
8. [Verify] Run health check to confirm resolution
This skill IS the troubleshooting skill. If the standard diagnostics do not identify the issue:
cat /private/tmp/telegram-bot.logls -lt ~/.claude/automation/claude-telegram-sync/logs/audit/afplay /System/Library/Sounds/Tink.aiff (if this fails, it is a macOS audio issue, not TTS)clean-component-removal then full-stack-bootstrapAfter this skill completes, reflect before closing the task:
Do NOT defer. The next invocation inherits whatever you leave behind.