README.md

Shell Wrapped - Your Terminal's Spotify Wrapped.

---

ShellWrapped is a CLI tool that analyzes your shell history (Bash or Zsh) and generates a "Wrapped" style summary of your year in the terminal. Discover your top commands, peak productivity hours, coding personality, and more, all presented in a beautiful, animated terminal UI with background lo-fi beats.

Features

• 📊 Command Stats: See your total command count and most used tools.
• 🕒 Productivity Analysis: Find out your most active days and times.
• 🧩 Personality Type: Get assigned a "Developer Persona" based on your command usage (e.g., "The Deployer," "The Tinkerer").
• 🎵 Vibe Check: Plays background lo-fi music while you view your stats (requires mpv).
• 🖼️ Shareable: Generates a summary card you can share with friends.
• 🚀 Fast & Local: Runs entirely on your machine; your history never leaves your computer.

Prerequisites

To enjoy the full experience (including background music), you need mpv installed on your system.

macOS:

brew install mpv

Linux (Ubuntu/Debian):

sudo apt install mpv

Windows: Install via Chocolatey (choco install mpv) or download from the official website.

Note: If mpv is not found, ShellWrapped will run silently.

Installation

Run directly with npx (recommended):

npx shellwrapped

Or install globally via npm or bun:

npm install -g shellwrapped
# or
bun add -g shellwrapped

Usage

Simply run the command in your terminal:

shellwrapped

By default, it analyzes the current year. You can specify a different year:

shellwrapped --year 2024

Options

Flag	Description
--year <YYYY>	Analyze a specific year (default: current year).
--quiet	Run without background music.
--config	Open configuration mode (if available).
--help	Show help message.

How It Works

ShellWrapped reads your shell history file (~/.bash_history or ~/.zsh_history). It parses the timestamps (if available) and commands to calculate statistics.

Privacy Note: All processing happens locally on your device. No data is sent to any server.

Troubleshooting

• "No history found": Ensure your shell is configured to save history. For Zsh, EXTENDED_HISTORY is often required for precise timestamps.
• "Music not playing": Verify mpv is installed and in your PATH. Check by running mpv --version.

Credits

• Background Music: Cali by Wataboi
  • Licensed under Creative Commons — Attribution 3.0 Unported — CC BY 3.0
  • Music promoted by Audio Library

Contributing

Contributions are welcome! See CONTRIBUTING.md for details.

License

MIT © ShellWrapped