GitHub - jcraigk/nerdflair: NerdFlair adds an attractive statusline and UI sounds to Claude Code

A configurable bash statusline and audio/spinner pack for Claude Code

Quick Start

/plugin marketplace add jcraigk/nerdflair
/plugin install nerdflair@jcraigk/nerdflair
/nerdflair install

Restart Claude Code after install for the changes to take effect.

Features

• 3 layout modes: full (3 rows), compact (2 rows), minimal (1 row)
• Context bar: color shifts from green to red as context fills, with a compaction threshold marker
• 3 color palettes: vibrant (full color), muted (desaturated), mono (grayscale)
• Custom spinner verbs: 150 themed thinking/working phrases
• Terminal bell: (tab indicator) on Notification, PermissionRequest, and Stop events
• Audio chimes (macOS, Linux): 20 styles, configurable per-event, adjustable volume
• Project folder display: always shows the launch directory, not the current subdirectory Claude may have navigated to
• Git branch, files edited, and lines added/removed
• Model name with output style indicator
• Active MCP servers
• Session cost, API duration, and token throughput

Prerequisites

A Nerd Font is required. The statusline uses Nerd Font glyphs for icons and Powerline caps. Without one installed, characters render as boxes.

Install via Homebrew or download from nerdfonts.com:

brew install --cask font-jetbrains-mono-nerd-font

Usage

Use the /nerdflair command to configure the statusline:

Cursor / VS Code Extension

A lightweight extension brings NerdFlair's audio chimes to Cursor (or VS Code). It reuses the same 20 chime styles from the Claude Code plugin.

What's included

• Random style per session — one of 20 chime styles is chosen at random each time the editor opens
• Audio chimes via Cursor hooks — SessionStart, Stop, and SessionEnd sounds
• Status bar — shows the current style; click to cycle through all 20

Install

Clone the repo and symlink the extension into your editor's extensions directory:

git clone https://github.com/jcraigk/nerdflair.git ~/nerdflair

# Cursor
ln -s ~/nerdflair/cursor-extension ~/.cursor/extensions/nerdflair-chimes

# VS Code (if using VS Code instead)
ln -s ~/nerdflair/cursor-extension ~/.vscode/extensions/nerdflair-chimes

Then add the hooks config at ~/.cursor/hooks.json (adjust the path if you cloned elsewhere):

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "command": "bash ~/nerdflair/cursor-extension/play-chime.sh SessionStart"
      }
    ],
    "stop": [
      {
        "command": "bash ~/nerdflair/cursor-extension/play-chime.sh Stop"
      }
    ],
    "sessionEnd": [
      {
        "command": "bash ~/nerdflair/cursor-extension/play-chime.sh SessionEnd"
      }
    ]
  }
}

Restart the editor. You should hear a startup chime and see the style name in the status bar.

Settings

Search "nerdflair" in Settings to configure:

Note: The extension requires jq and afplay (macOS) or paplay (Linux) for audio playback.

How It Works (Claude Code)

Three bash scripts and one JSON state file.

• Renderer (scripts/statusline.sh) — Claude Code pipes session JSON on every refresh. Reads state, outputs ANSI-colored statusline.
• Configurator (scripts/nerdflair.sh) — Handles /nerdflair commands. Reads and writes the state file.
• Hook Handler (hooks/bell.sh) — Fired on Claude Code events. Sends terminal bell and plays audio chimes (macOS, Linux) based on user-defined config.

All settings persist in ~/.claude/nerdflair/state.json. Per-session data (chime style) is stored as JSON in ~/.claude/nerdflair/sessions/ and cleaned up automatically.

Update

/plugin update nerdflair
/nerdflair install

/plugin update pulls the latest version. /nerdflair install refreshes the statusline config while preserving your existing settings. Restart Claude Code after updating.

Uninstall

/nerdflair uninstall
/plugin uninstall nerdflair

/nerdflair uninstall removes nerdflair's statusline, spinner verbs, and data from ~/.claude/. /plugin uninstall removes the plugin itself. Restart Claude Code after uninstalling.