Settings and Tuning
Configure all adjustable parameters for the TTS engine, Telegram bot, and supporting infrastructure. Defaults live in the bot's moon.yml env: block; the launchd service reads overrides from the bot directory's .env, because proto shims do not inject moon env (see config-architecture.md).
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 |
|---|---|---|
| moon | Yes | proto install in the bot directory (for tasks) |
| Bot running | Recommended | Changes to TTS/queue settings require bot restart |
Workflow Phases
Phase 0: Read Current Configuration
Read the current settings — defaults in moon.yml env:, launchd-service overrides in .env (print key names only; .env also holds secrets):
sed -n '/^env:/,/^tasks:/p' ~/.claude/automation/claude-telegram-sync/moon.yml
sed -E 's/=.*/=<set>/' ~/.claude/automation/claude-telegram-sync/.env
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 the env: block of ~/.claude/automation/claude-telegram-sync/moon.yml, and set the same key in that directory's .env so the launchd service picks it up. 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: moon task
cd ~/.claude/automation/claude-telegram-sync && moon run telegram-sync: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 moon.yml env: block and .env key names
2. [Identify] Present config groups to user via AskUserQuestion
3. [Select] User selects setting category to modify
4. [Edit] Update moon.yml env: and .env 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 active
Post-Change Checklist
After modifying this skill:
- Verify all config groups in SKILL.md match the current moon.yml
env:block - 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, or value only in moon.yml | Set it in .env too (launchd service), then restart the bot |
| moon.yml parse error | Invalid YAML syntax | Check indentation and quote every value as a string |
| 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
- Config Architecture - moon.yml
env:vs.env, secret loading, moon tasks and the proto-pinned Bun - 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.