Settings and Tuning
Configure all adjustable parameters for the TTS engine, Telegram bot, and supporting infrastructure. All settings are centralized in the mise.toml SSoT.
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
- Changing TTS voice (English, Chinese, or macOS
sayvoices) - Adjusting speech speed
- Tuning TTS timeouts or queue depth
- Configuring notification rate limiting or circuit breakers
- Adjusting prompt executor throttling
- Modifying session picker limits
- Changing audit log retention
Requirements
| Component | Required | Installation |
|---|---|---|
| mise | Yes | brew install mise (for env loading) |
| Bot running | Recommended | Changes to TTS/queue settings require bot restart |
Workflow Phases
Phase 0: Read Current Configuration
Read the current mise.toml to see all active settings:
cat ~/.claude/automation/claude-telegram-sync/mise.tomlAll configurable values live in the [env] section. The file is the single source of truth for the entire stack.
Phase 1: Identify What to Change
Present the config groups to the user via AskUserQuestion. Config groups:
| Group | Settings | Description |
|---|---|---|
| TTS Voice | TTS_VOICE_EN, TTS_VOICE_ZH, TTS_VOICE_SAY_EN, TTS_VOICE_SAY_ZH | Voice selection per language |
| TTS Speed | TTS_SPEED | Speech rate multiplier |
| TTS Timeouts | TTS_GENERATE_TIMEOUT_MS, TTS_SAY_TIMEOUT_MS | Generation and playback timeouts |
| TTS Queue | TTS_MAX_QUEUE_DEPTH, TTS_STALE_TTL_MS, TTS_MAX_TEXT_LEN | Queue limits and staleness |
| TTS Signal | TTS_SIGNAL_SOUND | Signal sound path (empty to disable) |
| Rate Limiting | NOTIFICATION_MIN_INTERVAL_MS, SUMMARIZER_* | Notification and summarizer throttling |
| Prompt Executor | PROMPT_* | Prompt execution throttling and circuit breaker |
| Session Picker | SESSION_* | Session scanning and display limits |
| Audit | AUDIT_RETENTION_DAYS | Log retention period |
| Model | HAIKU_MODEL | Claude model for Agent SDK calls |
Phase 2: Edit Configuration
Edit the appropriate line(s) in ~/.claude/automation/claude-telegram-sync/mise.toml. Use the Edit tool to make precise changes to specific values.
Phase 3: Validate and Apply
- Verify the edited value is within the valid range (see Config Reference)
- If TTS, queue, or rate limiting settings changed, restart the bot:
# Option A: If using mise tasks
cd ~/.claude/automation/claude-telegram-sync && mise run bot:restart
# Option B: Manual restart
pkill -f "bun.*main.ts" && cd ~/.claude/automation/claude-telegram-sync && bun --watch run src/main.ts- Confirm new settings are active by checking bot logs or testing the affected feature
TodoWrite Task Templates
Template: Settings Adjustment
1. [Read] Read current mise.toml configuration
2. [Identify] Present config groups to user via AskUserQuestion
3. [Select] User selects setting category to modify
4. [Edit] Update mise.toml with new values
5. [Validate] Verify values are in valid range
6. [Apply] Restart bot to apply changes (if TTS or queue settings changed)
7. [Verify] Confirm new settings are activePost-Change Checklist
After modifying this skill:
- Verify all config groups in SKILL.md match current mise.toml
- Update config-reference.md if new env vars were added
- Test that changed settings take effect after bot restart
- Update
references/evolution-log.mdwith change description
Troubleshooting
| Issue | Cause | Solution |
|---|---|---|
| Settings not taking effect | Bot not restarted | Restart bot after changing mise.toml |
| mise.toml parse error | Invalid TOML syntax | Check for missing quotes or unescaped chars |
| Voice not found | Invalid voice name | Check voice catalog (Kokoro voices are case-sensitive) |
| Speed too fast/slow | Value out of range | Use 0.5 to 2.0 range for TTS_SPEED |
| Circuit breaker stuck open | Too many failures | Wait for breaker timeout or restart bot |
| Timeout too short | TTS generation slow on first run | Model warmup takes longer; increase timeout |
Reference Documentation
- Config Reference - Full reference table with all env vars, defaults, valid ranges, and component ownership
- mise.toml Reference - Hub/spoke mise architecture, secret loading, and task file structure
- Evolution Log - Change history for this skill
Post-Execution Reflection
After this skill completes, reflect before closing the task:
- 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.
- What failed? — Fix the instruction that caused it. If it could recur, add it as an anti-pattern.
- What worked better than expected? — Promote it to recommended practice. Document why.
- What drifted? — Any script, reference, or external dependency that no longer matches reality gets fixed now.
- 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.