youtube-music-cli-mcp-fork: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

@involvex/youtube-music-cli is a terminal-based music player for YouTube Music, built with React and TypeScript using Ink for terminal UI rendering. It provides a full-featured CLI music player with search, playback controls, queue management, and multiple UI themes.

Commands

Development

bun run dev          # TypeScript watch mode
bun run build        # Compile TypeScript to dist/
bun run start        # Run compiled CLI (dist/source/cli.js)

Code Quality

bun run format       # Format code with Prettier
bun run format:check # Check formatting without modifying
bun run lint         # Lint code with ESLint
bun run lint:fix     # Fix linting issues automatically
bun run typecheck    # Type check without emitting

Testing

bun run test         # Run prettier check + XO + AVA

The prebuild script automatically runs format → lint:fix → typecheck before building.

Architecture

Entry Points

• CLI Entry: source/cli.tsx - Parses CLI arguments with meow, handles direct commands (play, search, playlist)
• App Root: source/app.tsx → source/main.tsx - Root React component
• Compiled Binary: dist/source/cli.js (set as bin in package.json)

State Management Pattern

The codebase uses a custom store pattern built on React Context + useReducer:

• source/stores/player.store.tsx: Core player state (playback, queue, volume, shuffle/repeat). Exports PlayerProvider and usePlayer() hook. State transitions happen through action categories (PLAY, PAUSE, NEXT, SEEK, etc.)
• source/stores/favorites.store.tsx: Favorite tracks state management.
• source/stores/navigation.store.tsx: View navigation state
• source/contexts/theme.context.tsx: Theme management, exports ThemeProvider and useTheme() hook

Important: All stores follow the same pattern - Provider component wraps children, custom hook throws if used outside provider.