Lizard

Play a lizard sound for terminal commands and Claude Code chat events.

Choose Your Mode

• Terminal-only mode (quickest): install and run commands in the integrated terminal.
• Claude Code mode (extra setup): add a hooks block in ~/.claude/settings.json.

Install in 30 Seconds

1. Open Extensions in VS Code/Cursor.
2. Search for Lizard.
3. Click Install.
4. Reload the window.

Terminal-Only Setup (1 minute)

1. Keep lizard.enabled = true (default).
2. Open an integrated terminal.
3. Run:

echo hello

4. Optional manual test: run command palette action Lizard: Test Sound.
5. Optional diagnostics: run Lizard: Show Diagnostics to print backend and config info in Output -> Lizard.

Claude Code Setup (2-3 minutes)

1. Open Settings:

• Press Cmd + , on Mac (Ctrl + , on Windows/Linux).
• In the search box, type lizard.

2. Turn on these toggles:

• Lizard: Enabled
• Lizard › Claude Hooks: Enabled
• Lizard › Claude Hooks: Trigger User Prompt Submit
• Lizard › Claude Hooks: Trigger Stop

3. Open Command Palette:

• Press Cmd + Shift + P on Mac (Ctrl + Shift + P on Windows/Linux).
• Run: Lizard: Show Claude Hook Setup

4. Copy the generated JSON snippet.
5. Open ~/.claude/settings.json.
6. Paste the generated hooks block at top level, right after enabledPlugins.

Example shape:

{
  "env": {
    "...": "keep your existing values"
  },
  "enabledPlugins": {
    "...": true
  },
  "hooks": {
    "...": "paste the full output from Lizard: Show Claude Hook Setup"
  }
}

7. Restart Cursor.
8. Open a new integrated terminal.

Verification

Terminal mode checks

echo hello

You should hear the sound once when the command starts.

Claude mode checks

echo $LIZARD_HOOK_ENABLED
echo $LIZARD_HOOK_BASE_URL
claude

Send one prompt and wait for completion. You should hear sound on:

• UserPromptSubmit (when you send)
• Stop (when Claude finishes)

What It Does

• Terminal trigger: listens for integrated terminal command-start events.
• Claude trigger: listens for local Claude hook events (UserPromptSubmit, Stop).
• Playback path: native OS players first, webview fallback second.

Settings

• lizard.enabled: master on/off.
• lizard.volume: playback volume (0 to 1).
• lizard.debounceMs: minimum gap between plays in milliseconds.
• lizard.preferWebview: use webview before native players.
• lizard.claudeHooks.enabled: enable local Claude hook receiver.
• lizard.claudeHooks.triggerUserPromptSubmit: play on submit.
• lizard.claudeHooks.triggerStop: play on completion.
• lizard.claudeHooks.logRequests: log request metadata in Output -> Lizard (no payload contents).

If You Installed Claude Hooks Before 0.0.3

1. Update to the latest version of Lizard.
2. Run Lizard: Show Claude Hook Setup again.
3. Replace your previous Claude hooks command strings once.

Reason: starting in 0.0.3, LIZARD_HOOK_TOKEN is no longer exported to the shell environment and the hook token is stored in VS Code SecretStorage instead.

Common Mistakes

• Pasting hooks inside enabledPlugins instead of top-level JSON.
• Forgetting to reopen terminal after enabling Claude hooks.
• Keeping old hook commands that depend on $LIZARD_HOOK_TOKEN.

Troubleshooting by Mode

Terminal mode

1. Run Lizard: Test Sound.
2. Open View -> Output, choose Lizard, confirm playback logs.
3. Run Lizard: Show Diagnostics to print detected native backends and current settings.
4. On Windows, playback prefers WAV via PowerShell SoundPlayer for consistency, then tries ffplay if available.
5. On Linux, install one player: paplay, aplay, ffplay, or mpg123.

Claude mode

1. Verify:

echo $LIZARD_HOOK_ENABLED
echo $LIZARD_HOOK_BASE_URL

2. Re-run Lizard: Show Claude Hook Setup and re-paste hooks.
3. Confirm Claude runs in an integrated terminal (not external terminal).
4. Check View -> Output -> Lizard for auth or route errors.

Privacy & Security

• Hook server listens only on 127.0.0.1.
• Requests require x-lizard-token.
• Token is stored in VS Code SecretStorage.
• Token is not exported to shell environment variables.