Agent-Skills.md

Agent Skills: Kokoro TTS Server

Start/stop Kokoro TTS HTTP server. TRIGGERS - start tts server, kokoro server, tts http, stop tts server.

UncategorizedID: terrylica/cc-skills/server

Repository

terrylica/cc-skills
terrylicaLicense: MIT
264

Install this agent skill to your local

pnpm dlx add-skill https://github.com/terrylica/cc-skills/tree/HEAD/plugins/kokoro-tts/skills/server

Skill Files

Browse the full folder contents for server.

Download Skill

Loading file tree…

plugins/kokoro-tts/skills/server/SKILL.md

Skill Metadata

Name
server
Description
"Start/stop Kokoro TTS HTTP server. TRIGGERS - start tts server, kokoro server, tts http, stop tts server."

Kokoro TTS Server

Manage the Kokoro TTS HTTP server — an OpenAI-compatible /v1/audio/speech endpoint on localhost:8779.

Server Overview

The server provides:

  • GET /health — Health status JSON
  • GET /v1/models — List available models
  • POST /v1/audio/speech — Synthesize text to audio (WAV, MP3, Opus, PCM)

Quick Start

Start (foreground, for testing)

~/.local/share/kokoro/.venv/bin/python ~/.local/share/kokoro/tts_server.py

Start (launchd, for production)

Per the macOS launchd policy, the launchd plist must launch a compiled Swift binary (not a bash script). Guide the user through:

  1. Compile Swift launcher binary
  2. Create launchd plist at ~/Library/LaunchAgents/com.terryli.kokoro-tts-server.plist
  3. Bootstrap: launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.terryli.kokoro-tts-server.plist

Stop

launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.terryli.kokoro-tts-server.plist

Verify

curl -s http://127.0.0.1:8779/health | python3 -m json.tool

Expected: {"status": "ok", "provider": "kokoro-tts-mlx", "model": "mlx-community/Kokoro-82M-bf16", "device": "mlx-metal"}

Environment Variables

| Variable | Default | Purpose | | ---------------------- | ----------- | ---------------------- | | KOKORO_SERVER_PORT | 8779 | Listen port | | KOKORO_SERVER_HOST | 127.0.0.1 | Bind address | | KOKORO_DEFAULT_VOICE | af_heart | Default voice | | KOKORO_DEFAULT_LANG | en-us | Default language | | KOKORO_DEFAULT_SPEED | 1.0 | Speech speed (0.1–5.0) | | KOKORO_PLAY_LOCAL | 0 | Play via afplay |

Troubleshooting

| Issue | Cause | Solution | | ------------------- | ---------------------- | ------------------------------------------ | | Port already in use | Another server running | lsof -i :8779 to find, kill it | | Model load fails | Not installed | Run /kokoro-tts:install first | | Slow first request | Warmup synthesis | Normal — first request triggers model load |