hismetric

README

hismetric

A blazingly fast command-line tool to analyze your shell history and discover your command usage patterns.

📊 Command Frequency Report (Total: 11084 commands)
────────────────────────────────────────────────────────────

  Top Commands

   1. git                   4970  ████████████████████
   2. go                    1410  █████
   3. docker                 652  ██
   4. cd                     565  ██
   5. code                   514  ██

Features

• 📊 Frequency Analysis - See which commands you use most
• 🔍 Deep Filtering - Drill down into specific commands and subcommands
• 🎨 Beautiful Output - Colorful terminal output with bar charts
• 📁 Subcommand Stats - Discover your most used subcommand patterns
• 🚩 Flag Patterns - See which flags you use most frequently
• 📤 JSON Export - Export reports for further analysis
• ⚡ Streaming - Processes history via stdin for maximum portability

Installation

go install ella.to/hismetric@v0.0.1

Make sure $GOPATH/bin (or $HOME/go/bin) is in your PATH.

Usage

Pipe your shell history to hismetric:

# Basic usage - show top commands
history | hismetric

# For zsh users (recommended for full history)
cat ~/.zsh_history | hismetric

# For bash users
cat ~/.bash_history | hismetric

Filtering Commands

Use -q to filter and analyze specific commands:

# Analyze all git commands
history | hismetric -q git

# Analyze git commit specifically
history | hismetric -q "git commit"

# Go deeper - analyze git remote add
history | hismetric -q "git remote add"

# Analyze docker run patterns
history | hismetric -q "docker run"

Examples

Overall Command Frequency

$ cat ~/.zsh_history | hismetric

📊 Command Frequency Report (Total: 11084 commands)
────────────────────────────────────────────────────────────

  Top Commands

   1. git                   4970  ████████████████████
   2. go                    1410  █████
   3. docker                 652  ██
   4. cd                     565  ██
   5. code                   514  ██
   ...

Command-Specific Analysis

$ cat ~/.zsh_history | hismetric -q git

📊 Report for: git
────────────────────────────────────────────────────────────

  Total occurrences: 4970

  Usage Patterns

  git commit                                1248  ███████████████
  git status                                1067  ████████████
  git add .                                  507  ██████
  git push origin main                       124  █
  git checkout                               146  █
  ...

Deep Dive into Subcommands

$ cat ~/.zsh_history | hismetric -q "git commit"

📊 Report for: git commit
────────────────────────────────────────────────────────────

  Total occurrences: 1253

  Command: git commit
  Frequency: 1250

  🚩 Top 10 Flag Patterns
     -m=Clean up code                             30  ████████
     -m=Update the code                           10  ███
     -m=wip                                        9  ██
     -m=First init                                 4  █
     ...

Options

Flag	Description
-q <query>	Filter commands (e.g., git, git commit, docker run)
--all	Show all results instead of top 25
--asc	Sort by frequency ascending (least used first)
--desc	Sort by frequency descending (default)
--json	Output as JSON for programmatic use
--no-color	Disable colored output

Sorting

# Show least used commands first
history | hismetric --asc

# Show all commands, not just top 25
history | hismetric --all

# Combine: all commands, least used first
history | hismetric --all --asc

JSON Output

Export your analysis as JSON for further processing:

$ cat ~/.zsh_history | hismetric --json

{
  "total_commands": 11084,
  "commands": [
    {
      "command": "git",
      "count": 4970,
      "subcommands": [
        {"name": "commit", "count": 1252},
        {"name": "status", "count": 1070},
        {"name": "add", "count": 776}
      ]
    }
  ]
}

Filter and export:

# Export git analysis to file
cat ~/.zsh_history | hismetric -q git --json > git-analysis.json

# Pipe to jq for further processing
cat ~/.zsh_history | hismetric --json | jq '.commands[:5]'

Shell Integration

Zsh

Add an alias to your ~/.zshrc:

alias hm='cat ~/.zsh_history | hismetric'
alias hmq='cat ~/.zsh_history | hismetric -q'

# Usage:
# hm              - show all command frequencies
# hmq git         - show git patterns
# hmq "git commit" - show git commit patterns

Bash

Add to your ~/.bashrc:

alias hm='cat ~/.bash_history | hismetric'
alias hmq='cat ~/.bash_history | hismetric -q'

Fish

Add to your ~/.config/fish/config.fish:

alias hm='cat ~/.local/share/fish/fish_history | hismetric'

How It Works

hismetric parses shell history from stdin and:

1. Tokenizes each command into name, subcommands, and flags
2. Normalizes flags (sorted for consistent comparison)
3. Aggregates by command pattern based on your query
4. Displays frequency statistics with visual bar charts

It handles various history formats including:

• Plain command history (history output)
• Zsh extended history (: timestamp:duration;command)
• Heredocs and multi-line commands
• Quoted and escaped arguments

Use Cases

• 🔍 Discover Habits - Find out which commands you use most
• 📈 Track Patterns - See how your git commit messages evolve
• 🎯 Optimize Workflow - Identify commands worth aliasing
• 📊 Team Insights - Share usage patterns with your team (via JSON)
• 🧹 Clean Up - Find one-off commands cluttering your history

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.