glados-claude-plugin: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

A GLaDOS personality plugin with neural TTS for Cortex Code and Claude Code. Registers hooks (Stop, SessionEnd) that synthesize assistant responses into speech using Forward Tacotron + HiFiGAN, played via afplay/aplay.

Commands

# Install (downloads ~260MB models, sets up venv, registers hooks/skills/commands)
./install.sh

# Uninstall (removes models, venv, hooks, skills, commands, state dirs)
./uninstall.sh

# Manual server control
./plugin/bin/serve.sh          # Start TTS server (port 8124)
./plugin/bin/stop.sh           # Stop TTS server
curl http://localhost:8124/health  # Health check

# Syntax-check all shell scripts
for f in plugin/bin/*.sh plugin/lib/*.sh; do bash -n "$f"; done

No test suite exists. Validation is bash -n syntax checks and manual functional testing (activate → speak → mute/unmute → deactivate).

Architecture

Runtime State Lives Outside the Repo

All ephemeral state is stored in $GLADOS_STATE_DIR, resolved by plugin/lib/state-dir.sh:

• Cortex Code: ~/.snowflake/cortex/cache/glados/
• Claude Code: ~/.claude/cache/glados/
• Fallback: ~/.local/state/glados-tts/

Detection uses CORTEX_SESSION_ID / CLAUDE_SESSION_ID env vars. The state dir contains: sessions/, .muted, server.pid, server.log, audio/.

Key Patterns

• Session opt-in model: Audio only plays for sessions that explicitly activate via /glados. Session markers are empty files at $GLADOS_STATE_DIR/sessions/<session-id>.
• Shared library sourcing: All plugin/bin/*.sh scripts source plugin/lib/tts-helpers.sh, which in turn sources plugin/lib/state-dir.sh. This provides $GLADOS_STATE_DIR, $PID_FILE, $PLUGIN_ROOT, is_server_running(), and wait_for_server().
• Mute hierarchy: Global mute ($GLADOS_STATE_DIR/.muted) → session registration check → per-session mute (sessions/.muted-<id>).
• Async playback: speak.sh forks synthesis+playback into ( ... ) &>/dev/null & disown so the hook returns immediately and text displays without delay.
• Chunk splitting: Responses over 900 chars are split at sentence boundaries before synthesis (server has 1000-char limit).