claude-narrator

claude-narrator

A Claude Code CLI plugin that narrates what Claude is doing in real-time. Get audio and visual feedback as Claude reads files, runs commands, edits code, and more.

What it does

claude-narrator hooks into four Claude Code lifecycle events:

Event	Emoji	What it announces
SessionStart	🚀	Session started, resumed, cleared, or compacted
PreToolUse	🔊	Which tool is about to run, with context (filename, command, etc.)
PostToolUse	✅	Tool finished, what it did
Stop	🏁	Claude is done and waiting for your next prompt

All output goes to stderr so it never interferes with Claude's stdout.

Installation

Prerequisites

• Claude Code CLI
• jq for JSON parsing (brew install jq on macOS, apt install jq on Linux)
• say (macOS, built-in) or espeak (Linux) for text-to-speech (optional)

Install

git clone https://github.com/nerdynikhil/claude-narrator.git
cd claude-narrator
./install.sh --user      # all projects
# or
./install.sh --project   # current project only

Uninstall

./install.sh --user --uninstall
# or
./install.sh --project --uninstall

Configuration

Enable detailed logging

Set the environment variable before starting Claude:

export NARRATOR_DETAILED_LOG=1

Logs are written to logs/narration-YYYYMMDD.log with timestamps and tool details.

Choose a TTS voice

export NARRATOR_VOICE=Daniel    # macOS: try Samantha, Moira, Alex, etc.

List available macOS voices with say -v '?'. For espeak on Linux, use voices like en+f3 or en+m1.

When unset, the system default voice is used.

Disable text-to-speech

export NARRATOR_TTS=0

When set to 0, all TTS is skipped but emoji console output continues. If neither say nor espeak is installed, TTS is silently skipped regardless.

How it works

The install script adds hook entries to your Claude Code settings.json (either ~/.claude/settings.json for user-wide or .claude/settings.json for project-level). Each hook runs a small bash script that:

1. Reads the JSON event payload from stdin via jq
2. Prints an emoji-prefixed message to stderr
3. Optionally speaks the message via say/espeak in the background
4. Optionally writes to a timestamped log file
5. Exits with code 0 so Claude proceeds normally

File structure

claude-narrator/
├── .claude-plugin/
│   └── plugin.json          # Plugin manifest
├── hooks/
│   ├── hooks.json           # Hooks wiring configuration
│   ├── session-start.sh     # SessionStart handler
│   ├── pre-tool-use.sh      # PreToolUse handler
│   ├── post-tool-use.sh     # PostToolUse handler
│   └── stop.sh              # Stop handler
├── docs/
│   ├── quickstart.md        # Quick start guide
│   └── examples.md          # Customization examples
├── logs/                    # Log output (gitignored)
├── install.sh               # Installer/uninstaller
└── README.md

License

MIT