claude-persona 0.1.0

package/README.md

@@ -0,0 +1,134 @@
+# claude-persona
+
+Sound effects for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) sessions. Hear audio feedback when Claude starts a task, finishes responding, hits an error, and more.
+
+Ships with a default Warcraft 3 peasant sound pack. Easily configurable with your own sounds and situations.
+
+## Quick Start
+
+```bash
+# Install globally (works in all projects)
+npx claude-persona init --global
+
+# Or install for current project only
+npx claude-persona init --project
+```
+
+That's it. Start a Claude Code session and you'll hear sounds.
+
+## How It Works
+
+claude-persona installs [Claude Code hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) that play audio clips when specific events happen during a session. Everything is controlled by a single JSON config file.
+
+## Configuration
+
+After `init`, your config lives at:
+- **Global:** `~/.claude-persona/claude-persona.json`
+- **Project:** `.claude/persona/claude-persona.json`
+
+```json
+{
+  "persona": "peasant",
+  "situations": [
+    {
+      "name": "task-complete",
+      "trigger": "Stop",
+      "description": "Claude finished responding",
+      "sounds": ["готово.mp3", "я готов.wav", "да.wav"]
+    }
+  ]
+}
+```
+
+### Config fields
+
+| Field | Description |
+|---|---|
+| `persona` | Name of your sound pack. Maps to `sounds/<persona>/` directory. |
+| `situations` | Array of situations that trigger sounds. |
+
+### Situation fields
+
+| Field | Description |
+|---|---|
+| `name` | Unique identifier. For `flag` triggers, this becomes the flag name. |
+| `trigger` | What fires this situation (see trigger types below). |
+| `description` | Human-readable description. Used in CLAUDE.md for flag situations. |
+| `sounds` | Array of filenames in `sounds/<persona>/`. A random one is picked each time. |
+
+### Trigger types
+
+| Trigger | When it fires |
+|---|---|
+| `UserPromptSubmit` | User sends a prompt |
+| `Stop` | Claude finishes responding |
+| `PostToolUseFailure` | A tool call fails |
+| `SessionStart` | New session begins |
+| `SessionEnd` | Session ends |
+| `Notification` | Claude needs attention or permission |
+| `SubagentStart` | A subagent is spawned |
+| `SubagentStop` | A subagent finishes |
+| `PreToolUse` | Before a tool executes |
+| `PostToolUse` | After a tool succeeds |
+| `flag` | Detected via `<!-- persona:<name> -->` in Claude's response |
+| `spam` | User sending 3+ prompts within 15 seconds (overrides `UserPromptSubmit`) |
+
+Any [Claude Code hook event](https://docs.anthropic.com/en/docs/claude-code/hooks) can be used as a trigger.
+
+### Flag situations
+
+Situations with `"trigger": "flag"` are special. Claude self-inserts an HTML comment flag at the end of its response when the situation applies. The hook system detects it from the transcript.
+
+For this to work, `claude-persona init --project` appends instructions to your `CLAUDE.md`:
+
+```markdown
+<!-- persona:admitted-wrong -->   → Claude admits a mistake
+<!-- persona:found-bug -->        → Claude found or fixed a bug
+```
+
+You can add your own flag situations — just add an entry with `"trigger": "flag"` and re-run `init`.
+
+## CLI Commands
+
+```bash
+claude-persona init --global     # Install globally
+claude-persona init --project    # Install for current project
+claude-persona test              # List all situations
+claude-persona test task-complete # Play a random sound for "task-complete"
+claude-persona uninstall --global   # Remove global hooks
+claude-persona uninstall --project  # Remove project hooks
+```
+
+## Custom Sound Packs
+
+1. Create a directory: `sounds/my-character/`
+2. Add your audio files (WAV, MP3, M4A, OGG)
+3. Update `persona` in your config to `"my-character"`
+4. Reference the filenames in your situations
+
+Sound files are stored flat — all files for a persona go in one directory.
+
+## Adding Situations
+
+Just add an entry to the `situations` array in your config:
+
+```json
+{
+  "name": "subagent-stop",
+  "trigger": "SubagentStop",
+  "description": "A subagent finished its work",
+  "sounds": ["phew.wav", "finally.wav"]
+}
+```
+
+Re-run `claude-persona init` to register any new hook events.
+
+## Requirements
+
+- Node.js 18+
+- Claude Code CLI
+- Audio playback: `afplay` (macOS), `paplay` (Linux), or PowerShell (Windows)
+
+## License
+
+MIT

package/defaults/claude-persona.json

@@ -0,0 +1,82 @@
+{
+  "persona": "peasant",
+  "situations": [
+    {
+      "name": "prompt-submitted",
+      "trigger": "UserPromptSubmit",
+      "description": "User sends a prompt",
+      "sounds": [
+        "да господин.wav",
+        "угу.wav",
+        "хорошо.wav",
+        "ну я пошел.wav",
+        "опять работать.wav",
+        "чего.wav"
+      ]
+    },
+    {
+      "name": "task-complete",
+      "trigger": "Stop",
+      "description": "Claude finished responding",
+      "sounds": ["готово.mp3", "я готов.wav", "да.wav", "хорошо.wav"]
+    },
+    {
+      "name": "tool-failed",
+      "trigger": "PostToolUseFailure",
+      "description": "A tool call failed",
+      "sounds": [
+        "меня убьют.wav",
+        "ооо.wav",
+        "придется драться.wav",
+        "здесь нельзя строить.m4a"
+      ]
+    },
+    {
+      "name": "session-start",
+      "trigger": "SessionStart",
+      "description": "New session begins",
+      "sounds": ["опять работать.wav", "я готов.wav", "да господин.wav"]
+    },
+    {
+      "name": "session-end",
+      "trigger": "SessionEnd",
+      "description": "Session ends",
+      "sounds": ["смерть.mp3", "прощайте.wav", "ну я пошел.wav"]
+    },
+    {
+      "name": "notification",
+      "trigger": "Notification",
+      "description": "Claude needs attention or permission",
+      "sounds": ["на меня давят.wav", "чего.wav"]
+    },
+    {
+      "name": "subagent-start",
+      "trigger": "SubagentStart",
+      "description": "A subagent is spawned",
+      "sounds": ["работа не волк.wav"]
+    },
+    {
+      "name": "admitted-wrong",
+      "trigger": "flag",
+      "description": "Claude admits a mistake or corrects itself",
+      "sounds": [
+        "вам меня не жалко.wav",
+        "меня убьют.wav",
+        "ооо.wav",
+        "тебя бы так.wav"
+      ]
+    },
+    {
+      "name": "found-bug",
+      "trigger": "flag",
+      "description": "Claude found or fixed a bug",
+      "sounds": ["мы поймали ведьму.wav"]
+    },
+    {
+      "name": "spam-detected",
+      "trigger": "spam",
+      "description": "User sending too many prompts too fast",
+      "sounds": ["ты что ли король.wav", "на меня давят.wav", "тебя бы так.wav"]
+    }
+  ]
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { initCommand } from './init.js';
+import { testCommand } from './test.js';
+import { uninstallCommand } from './uninstall.js';
+const program = new Command();
+program
+    .name('claude-persona')
+    .description('Sound effects for Claude Code sessions')
+    .version('0.1.0');
+program
+    .command('init')
+    .description('Install claude-persona hooks into Claude Code')
+    .option('--global', 'Install globally (~/.claude-persona/ + ~/.claude/settings.json)')
+    .option('--project', 'Install for current project (.claude/persona/ + .claude/settings.local.json)')
+    .action(initCommand);
+program
+    .command('test [situation]')
+    .description('Play a random sound for a situation (or list all situations)')
+    .option('-c, --config <path>', 'Path to claude-persona.json config')
+    .action(testCommand);
+program
+    .command('uninstall')
+    .description('Remove claude-persona hooks from Claude Code')
+    .option('--global', 'Remove from global settings')
+    .option('--project', 'Remove from project settings')
+    .action(uninstallCommand);
+program.parse();

package/dist/cli/init.d.ts

@@ -0,0 +1,6 @@
+interface InitOptions {
+    global?: boolean;
+    project?: boolean;
+}
+export declare function initCommand(options: InitOptions): Promise<void>;
+export {};

package/dist/cli/init.js

@@ -0,0 +1,165 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { loadConfig, getRequiredHookEvents, hasFlagSituations } from '../config.js';
+/** Locate the package root (where sounds/ and defaults/ live) */
+function getPackageRoot() {
+    // When running from dist/cli/index.js, package root is ../../
+    return path.resolve(new URL('..', import.meta.url).pathname, '..');
+}
+export async function initCommand(options) {
+    const isGlobal = options.global ?? false;
+    const isProject = options.project ?? false;
+    if (!isGlobal && !isProject) {
+        console.log('Please specify --global or --project:\n');
+        console.log('  claude-persona init --global   # Install for all projects');
+        console.log('  claude-persona init --project  # Install for current project only');
+        process.exit(1);
+    }
+    const packageRoot = getPackageRoot();
+    const defaultConfigPath = path.join(packageRoot, 'defaults', 'claude-persona.json');
+    const defaultSoundsDir = path.join(packageRoot, 'sounds');
+    if (!fs.existsSync(defaultConfigPath)) {
+        console.error('Error: Default config not found at', defaultConfigPath);
+        process.exit(1);
+    }
+    // Determine target paths
+    let targetDir;
+    let settingsPath;
+    if (isGlobal) {
+        targetDir = path.join(os.homedir(), '.claude-persona');
+        settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+    }
+    else {
+        targetDir = path.join(process.cwd(), '.claude', 'persona');
+        settingsPath = path.join(process.cwd(), '.claude', 'settings.local.json');
+    }
+    const targetConfigPath = path.join(targetDir, 'claude-persona.json');
+    const targetSoundsDir = path.join(targetDir, 'sounds');
+    // 1. Create target directory
+    fs.mkdirSync(targetDir, { recursive: true });
+    // 2. Copy config (don't overwrite if exists)
+    if (fs.existsSync(targetConfigPath)) {
+        console.log(`  Config already exists at ${targetConfigPath}, skipping.`);
+    }
+    else {
+        fs.copyFileSync(defaultConfigPath, targetConfigPath);
+        console.log(`  Config: ${targetConfigPath}`);
+    }
+    // 3. Copy sounds
+    const config = loadConfig(targetConfigPath);
+    const personaSoundsSource = path.join(defaultSoundsDir, config.persona);
+    const personaSoundsTarget = path.join(targetSoundsDir, config.persona);
+    if (fs.existsSync(personaSoundsSource)) {
+        fs.mkdirSync(personaSoundsTarget, { recursive: true });
+        const files = fs.readdirSync(personaSoundsSource);
+        let copied = 0;
+        for (const file of files) {
+            const targetFile = path.join(personaSoundsTarget, file);
+            if (!fs.existsSync(targetFile)) {
+                fs.copyFileSync(path.join(personaSoundsSource, file), targetFile);
+                copied++;
+            }
+        }
+        console.log(`  Sounds: ${copied} files copied to ${personaSoundsTarget}`);
+    }
+    else {
+        console.log(`  No default sounds found for persona "${config.persona}".`);
+        fs.mkdirSync(personaSoundsTarget, { recursive: true });
+        console.log(`  Created empty sounds dir: ${personaSoundsTarget}`);
+    }
+    // 4. Register hooks in Claude settings
+    const handlerPath = path.join(packageRoot, 'dist', 'handler.js');
+    registerHooks(config, settingsPath, handlerPath, targetConfigPath);
+    // 5. Append CLAUDE.md flag instructions (project install only)
+    if (isProject && hasFlagSituations(config)) {
+        appendClaudeMdFlags(config);
+    }
+    console.log('\n  claude-persona installed successfully!\n');
+    console.log(`  Edit your config: ${targetConfigPath}`);
+    console.log(`  Add sounds to:    ${personaSoundsTarget}`);
+    console.log(`  Test it:          claude-persona test task-complete`);
+}
+function registerHooks(config, settingsPath, handlerPath, configPath) {
+    // Load existing settings
+    let settings = {};
+    if (fs.existsSync(settingsPath)) {
+        try {
+            settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+        }
+        catch {
+            // Start fresh if corrupt
+        }
+    }
+    if (!settings.hooks) {
+        settings.hooks = {};
+    }
+    const requiredEvents = getRequiredHookEvents(config);
+    const hasFlags = hasFlagSituations(config);
+    const handlerCmd = (event, extra = '') => `node "${handlerPath}" --event ${event} --config "${configPath}"${extra}`;
+    // Marker to identify our hooks for idempotent re-runs
+    const marker = 'claude-persona';
+    for (const event of requiredEvents) {
+        if (!settings.hooks[event]) {
+            settings.hooks[event] = [];
+        }
+        // Remove any existing claude-persona hooks for this event
+        settings.hooks[event] = settings.hooks[event].filter((m) => !m.hooks.some((h) => h.command.includes(marker)));
+        // Build hook entries for this event
+        const hookEntries = {
+            matcher: '',
+            hooks: [
+                { type: 'command', command: handlerCmd(event) },
+            ],
+        };
+        // For Stop event, add async flag scanner
+        if (event === 'Stop' && hasFlags) {
+            hookEntries.hooks.push({
+                type: 'command',
+                command: handlerCmd(event, ' --flags'),
+                async: true,
+            });
+        }
+        settings.hooks[event].push(hookEntries);
+    }
+    // Ensure settings directory exists
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+    console.log(`  Hooks: registered in ${settingsPath}`);
+}
+function appendClaudeMdFlags(config) {
+    const claudeMdPath = path.join(process.cwd(), 'CLAUDE.md');
+    const flagSituations = config.situations.filter((s) => s.trigger === 'flag');
+    if (flagSituations.length === 0)
+        return;
+    const marker = '## Persona Flags';
+    let content = '';
+    if (fs.existsSync(claudeMdPath)) {
+        content = fs.readFileSync(claudeMdPath, 'utf8');
+        // Don't append if already present
+        if (content.includes(marker)) {
+            console.log('  CLAUDE.md: persona flags section already exists, skipping.');
+            return;
+        }
+    }
+    const rows = flagSituations
+        .map((s) => `| \`<!-- persona:${s.name} -->\` | ${s.description} |`)
+        .join('\n');
+    const section = `
+${marker}
+
+When your response matches one of these situations, include the corresponding HTML comment flag **at the very end** of your text output. The hook system will detect it and play the appropriate sound.
+
+| Flag | When to use |
+|---|---|
+${rows}
+
+Rules:
+- Only include ONE flag per response, at the very end
+- Only use when the situation genuinely applies
+- The flag is invisible to markdown renderers but the hook script reads it from the transcript
+`;
+    content = content ? content.trimEnd() + '\n' + section : section.trimStart();
+    fs.writeFileSync(claudeMdPath, content);
+    console.log('  CLAUDE.md: appended persona flags section.');
+}

package/dist/cli/test.d.ts

@@ -0,0 +1,5 @@
+interface TestOptions {
+    config?: string;
+}
+export declare function testCommand(situation: string | undefined, options: TestOptions): Promise<void>;
+export {};

package/dist/cli/test.js

@@ -0,0 +1,47 @@
+import path from 'node:path';
+import os from 'node:os';
+import fs from 'node:fs';
+import { loadConfig, resolveSoundPath } from '../config.js';
+import { playRandom } from '../player.js';
+/** Resolve config path: explicit > project > global */
+function findConfig(explicit) {
+    if (explicit)
+        return explicit;
+    const projectConfig = path.join(process.cwd(), '.claude', 'persona', 'claude-persona.json');
+    if (fs.existsSync(projectConfig))
+        return projectConfig;
+    const globalConfig = path.join(os.homedir(), '.claude-persona', 'claude-persona.json');
+    if (fs.existsSync(globalConfig))
+        return globalConfig;
+    return null;
+}
+export async function testCommand(situation, options) {
+    const configPath = findConfig(options.config);
+    if (!configPath) {
+        console.error('No claude-persona.json found. Run `claude-persona init` first.');
+        process.exit(1);
+    }
+    const config = loadConfig(configPath);
+    const configDir = path.dirname(configPath);
+    if (!situation) {
+        // List all situations
+        console.log(`Persona: ${config.persona}\n`);
+        console.log('Situations:');
+        for (const s of config.situations) {
+            console.log(`  ${s.name.padEnd(20)} [${s.trigger}] ${s.sounds.length} sound(s) — ${s.description}`);
+        }
+        console.log(`\nTest a situation: claude-persona test <situation-name>`);
+        return;
+    }
+    const match = config.situations.find((s) => s.name === situation);
+    if (!match) {
+        console.error(`Unknown situation: "${situation}"`);
+        console.error('Available:', config.situations.map((s) => s.name).join(', '));
+        process.exit(1);
+    }
+    const soundPaths = match.sounds.map((s) => resolveSoundPath(configDir, config.persona, s));
+    console.log(`Playing "${match.name}" (${match.sounds.length} sound(s))...`);
+    await playRandom(soundPaths);
+    // Give audio time to finish
+    await new Promise((resolve) => setTimeout(resolve, 3000));
+}

package/dist/cli/uninstall.d.ts

@@ -0,0 +1,6 @@
+interface UninstallOptions {
+    global?: boolean;
+    project?: boolean;
+}
+export declare function uninstallCommand(options: UninstallOptions): Promise<void>;
+export {};

package/dist/cli/uninstall.js

@@ -0,0 +1,60 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+export async function uninstallCommand(options) {
+    const isGlobal = options.global ?? false;
+    const isProject = options.project ?? false;
+    if (!isGlobal && !isProject) {
+        console.log('Please specify --global or --project:\n');
+        console.log('  claude-persona uninstall --global   # Remove from global settings');
+        console.log('  claude-persona uninstall --project  # Remove from project settings');
+        process.exit(1);
+    }
+    let settingsPath;
+    let personaDir;
+    if (isGlobal) {
+        settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+        personaDir = path.join(os.homedir(), '.claude-persona');
+    }
+    else {
+        settingsPath = path.join(process.cwd(), '.claude', 'settings.local.json');
+        personaDir = path.join(process.cwd(), '.claude', 'persona');
+    }
+    // Remove hooks from settings
+    if (fs.existsSync(settingsPath)) {
+        try {
+            const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+            if (settings.hooks) {
+                let removed = 0;
+                for (const event of Object.keys(settings.hooks)) {
+                    const before = settings.hooks[event].length;
+                    settings.hooks[event] = settings.hooks[event].filter((m) => !m.hooks.some((h) => h.command.includes('claude-persona')));
+                    removed += before - settings.hooks[event].length;
+                    // Clean up empty arrays
+                    if (settings.hooks[event].length === 0) {
+                        delete settings.hooks[event];
+                    }
+                }
+                // Clean up empty hooks object
+                if (Object.keys(settings.hooks).length === 0) {
+                    delete settings.hooks;
+                }
+                fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+                console.log(`  Removed ${removed} hook(s) from ${settingsPath}`);
+            }
+        }
+        catch (err) {
+            console.error(`  Error reading ${settingsPath}:`, err);
+        }
+    }
+    else {
+        console.log(`  No settings file at ${settingsPath}`);
+    }
+    // Inform about sound files (don't auto-delete)
+    if (fs.existsSync(personaDir)) {
+        console.log(`\n  Sound files and config are still at: ${personaDir}`);
+        console.log('  Remove manually if no longer needed:');
+        console.log(`    rm -rf "${personaDir}"`);
+    }
+    console.log('\n  claude-persona uninstalled.');
+}

package/dist/config.d.ts

@@ -0,0 +1,17 @@
+import type { ClaudePersonaConfig, Situation, TriggerType } from './types.js';
+/** Load and validate a claude-persona.json config file */
+export declare function loadConfig(configPath: string): ClaudePersonaConfig;
+/** Resolve the full path to a sound file given the config location */
+export declare function resolveSoundPath(configDir: string, persona: string, soundFile: string): string;
+/** Get all situations that match a given trigger type */
+export declare function getSituationsForTrigger(config: ClaudePersonaConfig, trigger: TriggerType): Situation[];
+/** Get a situation by name */
+export declare function getSituationByName(config: ClaudePersonaConfig, name: string): Situation | undefined;
+/** Get all unique hook events that need to be registered */
+export declare function getRequiredHookEvents(config: ClaudePersonaConfig): string[];
+/** Check whether the config has any flag-type situations */
+export declare function hasFlagSituations(config: ClaudePersonaConfig): boolean;
+/** Check whether the config has a spam-type situation */
+export declare function hasSpamSituation(config: ClaudePersonaConfig): boolean;
+/** Get names of all flag-trigger situations (used as valid flag identifiers) */
+export declare function getFlagNames(config: ClaudePersonaConfig): string[];

package/dist/config.js

@@ -0,0 +1,58 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/** Load and validate a claude-persona.json config file */
+export function loadConfig(configPath) {
+    const raw = fs.readFileSync(configPath, 'utf8');
+    const config = JSON.parse(raw);
+    if (!config.persona || typeof config.persona !== 'string') {
+        throw new Error('Config must have a "persona" string');
+    }
+    if (!Array.isArray(config.situations) || config.situations.length === 0) {
+        throw new Error('Config must have a non-empty "situations" array');
+    }
+    return config;
+}
+/** Resolve the full path to a sound file given the config location */
+export function resolveSoundPath(configDir, persona, soundFile) {
+    return path.join(configDir, 'sounds', persona, soundFile);
+}
+/** Get all situations that match a given trigger type */
+export function getSituationsForTrigger(config, trigger) {
+    return config.situations.filter((s) => s.trigger === trigger);
+}
+/** Get a situation by name */
+export function getSituationByName(config, name) {
+    return config.situations.find((s) => s.name === name);
+}
+/** Get all unique hook events that need to be registered */
+export function getRequiredHookEvents(config) {
+    const events = new Set();
+    for (const situation of config.situations) {
+        if (situation.trigger === 'flag') {
+            // Flag situations are detected on Stop hook
+            events.add('Stop');
+        }
+        else if (situation.trigger === 'spam') {
+            // Spam overrides UserPromptSubmit
+            events.add('UserPromptSubmit');
+        }
+        else {
+            events.add(situation.trigger);
+        }
+    }
+    return [...events];
+}
+/** Check whether the config has any flag-type situations */
+export function hasFlagSituations(config) {
+    return config.situations.some((s) => s.trigger === 'flag');
+}
+/** Check whether the config has a spam-type situation */
+export function hasSpamSituation(config) {
+    return config.situations.some((s) => s.trigger === 'spam');
+}
+/** Get names of all flag-trigger situations (used as valid flag identifiers) */
+export function getFlagNames(config) {
+    return config.situations
+        .filter((s) => s.trigger === 'flag')
+        .map((s) => s.name);
+}

package/dist/flag-scanner.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Scan the transcript for persona flags in the last assistant message.
+ * Returns the first matching flag name, or null if none found.
+ */
+export declare function scanForFlags(transcriptPath: string, validFlags: string[]): string | null;

package/dist/flag-scanner.js

@@ -0,0 +1,53 @@
+import fs from 'node:fs';
+const FLAG_PATTERN = /<!--\s*persona:(\S+)\s*-->/g;
+/**
+ * Scan the transcript for persona flags in the last assistant message.
+ * Returns the first matching flag name, or null if none found.
+ */
+export function scanForFlags(transcriptPath, validFlags) {
+    if (!transcriptPath || !fs.existsSync(transcriptPath)) {
+        return null;
+    }
+    // Read last 30KB of transcript
+    const stat = fs.statSync(transcriptPath);
+    const readSize = Math.min(stat.size, 30 * 1024);
+    const fd = fs.openSync(transcriptPath, 'r');
+    const buffer = Buffer.alloc(readSize);
+    fs.readSync(fd, buffer, 0, readSize, Math.max(0, stat.size - readSize));
+    fs.closeSync(fd);
+    const tail = buffer.toString('utf8');
+    const lines = tail.split('\n').filter(Boolean);
+    // Find the last assistant message
+    let lastAssistantText = '';
+    for (let i = lines.length - 1; i >= 0; i--) {
+        try {
+            const entry = JSON.parse(lines[i]);
+            if (entry.role === 'assistant') {
+                if (typeof entry.content === 'string') {
+                    lastAssistantText = entry.content;
+                }
+                else if (Array.isArray(entry.content)) {
+                    lastAssistantText = entry.content
+                        .filter((b) => b.type === 'text')
+                        .map((b) => b.text ?? '')
+                        .join(' ');
+                }
+                break;
+            }
+        }
+        catch {
+            // Skip malformed lines
+        }
+    }
+    if (!lastAssistantText)
+        return null;
+    // Scan for persona flags
+    let match;
+    while ((match = FLAG_PATTERN.exec(lastAssistantText)) !== null) {
+        const flagName = match[1];
+        if (validFlags.includes(flagName)) {
+            return flagName;
+        }
+    }
+    return null;
+}

package/dist/handler.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * claude-persona hook handler
+ *
+ * Called by Claude Code hooks with:
+ *   node handler.js --event <HookEvent> [--flags] --config <path>
+ *
+ * Reads hook JSON from stdin, resolves a situation, plays a sound.
+ */
+export {};

package/dist/handler.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+/**
+ * claude-persona hook handler
+ *
+ * Called by Claude Code hooks with:
+ *   node handler.js --event <HookEvent> [--flags] --config <path>
+ *
+ * Reads hook JSON from stdin, resolves a situation, plays a sound.
+ */
+import path from 'node:path';
+import { loadConfig, resolveSoundPath, getSituationsForTrigger, getSituationByName, getFlagNames, hasSpamSituation, } from './config.js';
+import { playRandom, randomElement } from './player.js';
+import { checkSpam } from './spam-detector.js';
+import { scanForFlags } from './flag-scanner.js';
+// Safety timeout — never block Claude
+setTimeout(() => process.exit(0), 5000);
+function parseArgs(argv) {
+    let event = '';
+    let flags = false;
+    let config = '';
+    for (let i = 2; i < argv.length; i++) {
+        switch (argv[i]) {
+            case '--event':
+                event = argv[++i] ?? '';
+                break;
+            case '--flags':
+                flags = true;
+                break;
+            case '--config':
+                config = argv[++i] ?? '';
+                break;
+        }
+    }
+    return { event, flags, config };
+}
+async function readStdin() {
+    return new Promise((resolve) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => { data += chunk; });
+        process.stdin.on('end', () => resolve(data));
+        // If stdin isn't piped, resolve immediately
+        if (process.stdin.isTTY)
+            resolve('{}');
+    });
+}
+async function main() {
+    const args = parseArgs(process.argv);
+    if (!args.config) {
+        process.exit(0);
+    }
+    let hookInput;
+    try {
+        const raw = await readStdin();
+        hookInput = JSON.parse(raw || '{}');
+    }
+    catch {
+        hookInput = { session_id: '', hook_event_name: args.event };
+    }
+    let personaConfig;
+    try {
+        personaConfig = loadConfig(args.config);
+    }
+    catch {
+        process.exit(0);
+    }
+    const configDir = path.dirname(args.config);
+    // Flag scanning mode (async Stop hook)
+    if (args.flags) {
+        const flagNames = getFlagNames(personaConfig);
+        if (flagNames.length === 0 || !hookInput.transcript_path) {
+            process.exit(0);
+        }
+        const matchedFlag = scanForFlags(hookInput.transcript_path, flagNames);
+        if (matchedFlag) {
+            const situation = getSituationByName(personaConfig, matchedFlag);
+            if (situation) {
+                const soundPaths = situation.sounds.map((s) => resolveSoundPath(configDir, personaConfig.persona, s));
+                await playRandom(soundPaths);
+            }
+        }
+        // Give sound time to start before exiting
+        await new Promise((resolve) => setTimeout(resolve, 1500));
+        process.exit(0);
+    }
+    // Normal mode: resolve situation from event
+    let situation;
+    if (args.event === 'UserPromptSubmit' && hasSpamSituation(personaConfig)) {
+        const isSpam = checkSpam();
+        if (isSpam) {
+            const spamSituations = getSituationsForTrigger(personaConfig, 'spam');
+            situation = spamSituations.length > 0 ? randomElement(spamSituations) : undefined;
+        }
+    }
+    if (!situation) {
+        const matches = getSituationsForTrigger(personaConfig, args.event);
+        situation = matches.length > 0 ? matches[0] : undefined;
+    }
+    if (!situation || situation.sounds.length === 0) {
+        process.exit(0);
+    }
+    const soundPaths = situation.sounds.map((s) => resolveSoundPath(configDir, personaConfig.persona, s));
+    await playRandom(soundPaths);
+    process.exit(0);
+}
+main().catch(() => process.exit(0));

package/dist/player.d.ts

@@ -0,0 +1,6 @@
+/** Pick a random element from an array */
+export declare function randomElement<T>(arr: T[]): T;
+/** Play a single sound file. Silently fails if file missing or playback errors. */
+export declare function play(filePath: string): Promise<void>;
+/** Pick a random sound from a list of file paths and play it */
+export declare function playRandom(filePaths: string[]): Promise<void>;

package/dist/player.js

@@ -0,0 +1,29 @@
+import fs from 'node:fs';
+// @ts-expect-error no types for play-sound
+import playSound from 'play-sound';
+const player = playSound();
+/** Pick a random element from an array */
+export function randomElement(arr) {
+    return arr[Math.floor(Math.random() * arr.length)];
+}
+/** Play a single sound file. Silently fails if file missing or playback errors. */
+export function play(filePath) {
+    return new Promise((resolve) => {
+        if (!fs.existsSync(filePath)) {
+            resolve();
+            return;
+        }
+        player.play(filePath, (err) => {
+            if (err && err.killed !== true) {
+                // Silently fail — don't block Claude
+            }
+            resolve();
+        });
+    });
+}
+/** Pick a random sound from a list of file paths and play it */
+export function playRandom(filePaths) {
+    if (filePaths.length === 0)
+        return Promise.resolve();
+    return play(randomElement(filePaths));
+}

package/dist/spam-detector.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Record a prompt timestamp and check if the user is spamming.
+ * Returns true if 3+ prompts were submitted within 15 seconds.
+ */
+export declare function checkSpam(): boolean;

package/dist/spam-detector.js

@@ -0,0 +1,31 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+const STAMP_FILE = path.join(os.tmpdir(), 'claude-persona-stamps.json');
+const SPAM_WINDOW_MS = 15_000;
+const SPAM_THRESHOLD = 3;
+function getTimestamps() {
+    try {
+        if (fs.existsSync(STAMP_FILE)) {
+            return JSON.parse(fs.readFileSync(STAMP_FILE, 'utf8'));
+        }
+    }
+    catch {
+        // ignore corrupt file
+    }
+    return [];
+}
+function saveTimestamps(stamps) {
+    fs.writeFileSync(STAMP_FILE, JSON.stringify(stamps));
+}
+/**
+ * Record a prompt timestamp and check if the user is spamming.
+ * Returns true if 3+ prompts were submitted within 15 seconds.
+ */
+export function checkSpam() {
+    const now = Date.now();
+    const stamps = getTimestamps().filter((t) => now - t < SPAM_WINDOW_MS);
+    stamps.push(now);
+    saveTimestamps(stamps);
+    return stamps.length >= SPAM_THRESHOLD;
+}

package/dist/types.d.ts

@@ -0,0 +1,64 @@
+/** All Claude Code hook event names that can be used as triggers */
+export type HookEvent = 'UserPromptSubmit' | 'Stop' | 'PreToolUse' | 'PostToolUse' | 'PostToolUseFailure' | 'SessionStart' | 'SessionEnd' | 'Notification' | 'SubagentStart' | 'SubagentStop' | 'TeammateIdle' | 'TaskCompleted' | 'PreCompact' | 'PermissionRequest';
+/** Special trigger types beyond hook events */
+export type SpecialTrigger = 'flag' | 'spam';
+/** All valid trigger values */
+export type TriggerType = HookEvent | SpecialTrigger;
+/** A situation that triggers a sound */
+export interface Situation {
+    /** Unique name, also used as flag identifier for flag triggers */
+    name: string;
+    /** What triggers this situation */
+    trigger: TriggerType;
+    /** Human-readable description of when this plays */
+    description: string;
+    /** Sound filenames (resolved relative to sounds/<persona>/) */
+    sounds: string[];
+}
+/** The user-facing config file */
+export interface ClaudePersonaConfig {
+    /** Name of the sound pack / character (maps to sounds/<persona>/) */
+    persona: string;
+    /** All configured situations */
+    situations: Situation[];
+}
+/** JSON payload from Claude Code hooks via stdin */
+export interface HookInput {
+    session_id: string;
+    transcript_path?: string;
+    cwd?: string;
+    hook_event_name: string;
+    permission_mode?: string;
+    prompt?: string;
+    tool_name?: string;
+    tool_input?: Record<string, unknown>;
+    tool_response?: string;
+    tool_use_id?: string;
+    message?: string;
+    title?: string;
+    notification_type?: string;
+    source?: string;
+    model?: string;
+    stop_hook_active?: boolean;
+}
+/** Structure of Claude Code settings.json hooks section */
+export interface ClaudeHookEntry {
+    type: 'command';
+    command: string;
+    async?: boolean;
+    timeout?: number;
+}
+export interface ClaudeHookMatcher {
+    matcher: string;
+    hooks: ClaudeHookEntry[];
+}
+export interface ClaudeSettings {
+    hooks?: Record<string, ClaudeHookMatcher[]>;
+    [key: string]: unknown;
+}
+/** CLI handler args parsed from process.argv */
+export interface HandlerArgs {
+    event: string;
+    flags: boolean;
+    config: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/hooks/hooks.json

@@ -0,0 +1,86 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PLUGIN_ROOT/dist/handler.js\" --event UserPromptSubmit --config \"$CLAUDE_PLUGIN_ROOT/defaults/claude-persona.json\""
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PLUGIN_ROOT/dist/handler.js\" --event Stop --config \"$CLAUDE_PLUGIN_ROOT/defaults/claude-persona.json\""
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PLUGIN_ROOT/dist/handler.js\" --event Stop --flags --config \"$CLAUDE_PLUGIN_ROOT/defaults/claude-persona.json\"",
+            "async": true
+          }
+        ]
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PLUGIN_ROOT/dist/handler.js\" --event PostToolUseFailure --config \"$CLAUDE_PLUGIN_ROOT/defaults/claude-persona.json\""
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PLUGIN_ROOT/dist/handler.js\" --event SessionStart --config \"$CLAUDE_PLUGIN_ROOT/defaults/claude-persona.json\""
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PLUGIN_ROOT/dist/handler.js\" --event SessionEnd --config \"$CLAUDE_PLUGIN_ROOT/defaults/claude-persona.json\""
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PLUGIN_ROOT/dist/handler.js\" --event Notification --config \"$CLAUDE_PLUGIN_ROOT/defaults/claude-persona.json\""
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PLUGIN_ROOT/dist/handler.js\" --event SubagentStart --config \"$CLAUDE_PLUGIN_ROOT/defaults/claude-persona.json\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "claude-persona",
+  "version": "0.1.0",
+  "description": "Sound effects for Claude Code sessions — configurable audio feedback for hooks and events",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "claude-persona": "./dist/cli/index.js"
+  },
+  "main": "./dist/handler.js",
+  "files": [
+    "dist",
+    "sounds",
+    "defaults",
+    "hooks",
+    "plugin.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "play-sound": "^1.1.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "hooks",
+    "sound",
+    "audio",
+    "persona",
+    "notifications"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/baunov/claude-persona.git"
+  }
+}

package/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "claude-persona",
+  "version": "0.1.0",
+  "description": "Sound effects for Claude Code sessions — configurable audio feedback for hooks and events"
+}