Settings And Tuning

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 say voices)
• 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

---

Workflow Phases

Phase 0: Read Current Configuration

Read the current mise.toml to see all active settings:

cat ~/.claude/automation/claude-telegram-sync/mise.toml

All 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:

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

1. Verify the edited value is within the valid range (see Config Reference) 2. 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

1. 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 active

---

Post-Change Checklist

After modifying this skill:

1. [ ] Verify all config groups in SKILL.md match current mise.toml 2. [ ] Update config-reference.md if new env vars were added 3. [ ] Test that changed settings take effect after bot restart 4. [ ] Update references/evolution-log.md with change description

Troubleshooting

---

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:

0. 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. 1. What failed? — Fix the instruction that caused it. If it could recur, add it as an anti-pattern. 2. What worked better than expected? — Promote it to recommended practice. Document why. 3. What drifted? — Any script, reference, or external dependency that no longer matches reality gets fixed now. 4. 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.

---

---

Configuration Reference

Complete reference for all environment variables in ~/.claude/automation/claude-telegram-sync/mise.toml.

Config SSoT

All settings live in the [env] section of mise.toml. The bot and shell scripts read these as environment variables. All values are strings in TOML (mise convention).

---

TTS Voice Configuration

Notes:

• Kokoro voices are case-sensitive. Use tts_kokoro_audition.sh to preview voices.
• macOS say voices: list available with say -v '?'
• TTS_VOICE_EN and TTS_VOICE_ZH are used by the Kokoro engine (higher quality)
• TTS_VOICE_SAY_EN and TTS_VOICE_SAY_ZH are fallback voices using macOS say

TTS Speed

Notes:

• 1.0 is normal speed
• 1.25 is the default (slightly faster for efficiency)
• Values below 0.5 or above 2.0 may produce distorted audio

TTS Timeouts

Notes:

• TTS_GENERATE_TIMEOUT_MS: Maximum time to wait for Kokoro to generate a WAV chunk
• TTS_SAY_TIMEOUT_MS: Maximum time for the entire TTS playback (all chunks)
• First-run generation is slower due to model warmup; subsequent calls are faster

TTS Queue

Notes:

• TTS_MAX_QUEUE_DEPTH: Maximum pending TTS jobs. New requests are dropped if queue is full.
• TTS_STALE_TTL_MS: Time-to-live for queued items. Stale items are discarded (2 min default).
• TTS_MAX_TEXT_LEN: Maximum text length accepted for TTS. Longer text is truncated.

TTS Signal Sound

Notes:

• Plays a short sound to indicate TTS is processing (non-blocking)
• Set to empty string "" to disable the signal sound
• macOS system sounds are in /System/Library/Sounds/

Notification Rate Limiting

Notes:

• NOTIFICATION_MIN_INTERVAL_MS: Minimum gap between Telegram notifications (prevents spam)
• SUMMARIZER_MIN_INTERVAL_MS: Minimum gap between summarization API calls
• SUMMARIZER_CIRCUIT_BREAKER_MS: Cooldown period after SUMMARIZER_MAX_FAILURES consecutive failures (5 min default)
• Circuit breaker resets after the cooldown period, allowing retries

Prompt Executor

Notes:

• PROMPT_MIN_INTERVAL_MS: Minimum gap between prompt executions (30s default)
• PROMPT_EXECUTION_TIMEOUT_MS: Maximum time for a single prompt execution (2 min default)
• PROMPT_EDIT_THROTTLE_MS: Debounce for edit detection (prevents rapid re-execution)
• PROMPT_CIRCUIT_BREAKER_MS: Cooldown after consecutive failures (10 min default)

Session Picker

Notes:

• SESSION_SCAN_LIMIT: Maximum sessions to scan from filesystem
• SESSION_DISPLAY_LIMIT: Maximum sessions shown in Telegram picker UI
• SESSION_MAX_AGE_DAYS: Sessions older than this are excluded
• SESSION_PENDING_TTL_MS: Time to wait for user to pick a session before timing out (5 min default)

Audit Logging

Notes:

• Audit logs older than this are eligible for cleanup
• Logs are stored in ~/.claude/automation/claude-telegram-sync/logs/audit/

Model Configuration

Notes:

• Used for summarization and other Agent SDK calls in the bot
• Change this when a newer Haiku model is released

settings-and-tuning Evolution Log

mise.toml Architecture Reference

How the tts-tg-sync bot uses mise.toml for configuration, secret loading, and task orchestration.

Hub/Spoke Structure

~/.claude/automation/claude-telegram-sync/
├── mise.toml              # Hub: [tools] + [env] (SSoT for all config)
├── .mise.local.toml       # Secrets: _.file loads BOT_TOKEN/CHAT_ID (gitignored)
├── .mise/
│   └── tasks/
│       ├── bot.toml       # Spoke: bot lifecycle tasks (start, stop, restart, logs)
│       └── validate.toml  # Spoke: validation DAG tasks
└── src/                   # TypeScript bot source

Hub: mise.toml

The root mise.toml owns two responsibilities:

1. [tools]: Runtime versions (Bun) 2. [env]: All configuration as environment variables

[tools]
bun = "1.3"

[env]
# All 30+ config values live here
TTS_VOICE_EN = "af_heart"
TTS_SPEED = "1.25"
# ... (see config-reference.md for full list)

[task_config]
includes = [".mise/tasks/bot.toml", ".mise/tasks/validate.toml"]

Secrets: .mise.local.toml

Secrets are loaded from a separate file that is gitignored:

# .mise.local.toml (NEVER committed to git)
[env]
_.file = "{{env.HOME}}/.claude/.secrets/ccterrybot-telegram"

The secrets file contains:

BOT_TOKEN=<telegram-bot-token>
CHAT_ID=<telegram-chat-id>

Why \_.file for Secrets

The _.file directive loads a dotenv-style file as environment variables. Benefits:

• Secrets stay in a single file at ~/.claude/.secrets/ (not in mise.toml)
• The .mise.local.toml is gitignored, so the _.file path itself is not committed
• Same pattern used across all projects with secrets

Spoke: Task Files

Task files are included via [task_config].includes in the hub. They define bot lifecycle operations.

bot.toml (Core Tasks)

Typical tasks:

validate.toml (Validation DAG)

Validation tasks for checking configuration and health. Tasks can depend on each other to form a validation DAG.

Environment Variable Flow

mise.toml [env]          (default values, committed)
    │
    ├── .mise.local.toml (secrets via _.file, gitignored)
    │
    └── Environment Variables
         │
         ├── TypeScript bot (process.env.VAR)
         ├── Shell scripts (${VAR:-default})
         └── Python scripts (os.environ.get("VAR", "default"))

All components use the same environment variables with fallback defaults, so they work both with and without mise.

Editing Guidelines

When editing mise.toml:

1. All values are strings in TOML (mise convention). Use quotes: TTS_SPEED = "1.25" 2. Group related settings with comment headers (e.g., # --- TTS Voice Configuration ---) 3. Never put secrets in mise.toml. Use .mise.local.toml with _.file 4. Restart the bot after changing values (mise loads env on process start, not dynamically)

Template Syntax

mise uses Tera templates in TOML values:

[env]
# Reference HOME directory
KOKORO_VENV = "{{env.HOME}}/.local/share/kokoro/.venv"

# Reference config_root (directory containing mise.toml)
LOCAL_SCRIPTS = "{{config_root}}/scripts"

Common template variables: