Terminal-Wrapped

Inspired from Spotify Wrapped

🚀 Terminal-Wrapped is a Python tool that generates insightful statistics and visualizations from your terminal command history. It supports Bash, Zsh, and Fish shells, and provides a web interface to display your command usage patterns in a fun and informative way.

🌟 Features

• Multi-Shell Support: Automatically detects and parses history files from Bash, Zsh, and Fish shells.
• Usage Statistics:
  • General: Total commands, Vocabulary size, Longest command, Weirdest commands.
  • Activity: Most active day, Weekend activity, Longest Daily Streak, Night Owl vs Early Bird.
  • Power User: Sudo usage, Git usage, Pipe mastery, Complexity score.
  • Habits: Editor preference (Editor Wars), Package manager usage, Directory hopping.
  • Personality: Clean Freak, Help Seeker, The Connector, Friday Deployer, Commit Vibes.
• Visualizations:
  • Spotify-Wrapped Style Slides: Navigate through your terminal journey with interactive slides.
  • Dashboard: Comprehensive summary view with charts for Hourly/Monthly activity, Editor usage, and Package ecosystems.
• Local Web Interface: Starts a Flask web server to display statistics and charts in a user-friendly interface.

🏃 Quickstart

To quickly set up and run Terminal-Wrapped, you can use the following command:

curl -s https://raw.githubusercontent.com/victor-gurbani/terminal-wrapped/main/quickstart.sh | bash

🚀 Installation

1. Clone the repository:

   git clone https://github.com/victor-gurbani/terminal-wrapped.git
   cd terminal-wrapped
   

2. Create a virtual environment (optional but recommended):

   python3 -m venv venv
   source venv/bin/activate
   

3. Install the required dependencies:

   pip install -r requirements.txt
   

📈 Usage

Run the main.py script to generate your terminal usage statistics:

python main.py

Options

• Specify Shell: By default, the script attempts to detect your current shell. To specify a shell manually, use the --shell option:

  python main.py --shell bash
  

  Supported shells are bash, zsh, and fish.

• Specify History File: To use a custom history file, use the --history option:

  python main.py --history /path/to/history_file
  

🌐 Viewing the Results

The script outputs statistics to the console and starts a Flask web server at http://0.0.0.0:8081.

Open your web browser and navigate to http://localhost:8081 to view your terminal usage wrapped in an interactive web interface with charts.

[!NOTE]

To ensure time-specific statistics are shown, check that the following are enabled for your shell:

• For Zsh - EXTENDED_HISTORY (oh-my-zsh has it enabled by default)
• For Bash - HISTTIMEFORMAT

Commands executed before configuring the option won't be recorded with a timestamp, affecting the stats.

📋 Dependencies

• Python 3.x
• Flask
• Collections (built-in)
• Datetime (built-in)
• Threading (built-in)
• Argparse (built-in)
• JSON (built-in)
• Regular Expressions (built-in)
• Chart.js (for rendering charts in the web interface)

📁 Project Structure

terminal-wrapped/
├── main.py
├── README.md
└── templates/
        └── index.html

• main.py: The main script that parses the history file, generates statistics, and starts the web server.
• index.html: The HTML template for the web interface.

🤝 Contributing

Contributions are welcome! Feel free to submit issues or pull requests to improve the project.

Star History

📜 License

This project is licensed under the MIT License. See the LICENSE file for more details.

ToDo:

• Aggregate history stats from other available sources such as proot
• Improve logic to remove the aggregated commands that are saved when you first enable time-specific stats