freq - Shell History Analyzer

Features:

• Multi-shell support - Works with both Bash and Zsh
• Smart analysis - Basic stats or detailed breakdowns
• Command-specific analysis - Deep dive into specific commands and their variations
• Timeline tracking - See usage patterns over time
• Alias resolution - Resolves shell aliases to show actual command usage
• Flexible filtering - Filter by date ranges, exclude commands, analyze specific time periods
• Command correlations - Find commands often used together
• Export reports - Save analysis to files

Quick Start:

# Clone and install
git clone https://github.com/Tecttano/freq.git
cd freq
chmod +x install.sh
./install.sh

# Basic usage
freq # Show top 10 commands
freq -n 20 # Show top 20 commands
freq -a # Detailed analysis

Installation:

Quick Install

• Clone the repository:

git clone https://github.com/Tecttano/freq.git
cd freq

• Run the installation script:

chmod +x install.sh
./install.sh

• Start using freq:

freq
freq -a
freq -c git

Manual Installation

If you prefer to install manually:

# Copy to system directory
sudo cp freq.py /usr/local/bin/freq
sudo chmod +x /usr/local/bin/freq

User Installation (No sudo required)

If you don't have sudo access:

# Create local bin directory
mkdir -p ~/.local/bin

# Copy the script
cp freq.py ~/.local/bin/freq
chmod +x ~/.local/bin/freq

# Add to PATH (add this to your ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.local/bin:$PATH"

# Reload your shell
source ~/.bashrc # or source ~/.zshrc

Usage Examples:

Basic Analysis

freq # Top 10 commands
freq -n 5 # Top 5 commands
freq -n 20 # Top 20 commands

Advanced Analysis

freq -a # Detailed breakdown with stats
freq -a -n 15 # Detailed analysis, top 15 commands

Command-Specific Analysis

freq -c git # Analyze all git command variations
freq -c python3 # Analyze python3 usage patterns
freq -c git --timeline # Git usage with timeline
freq -c npm --correlations # Commands often used with npm

Date Filtering

freq -d today # Today's commands only
freq -d week # Last 7 days
freq -d month # Last 30 days
freq -d 2025-05-01 # Specific date
freq -d 2025-05-01:2025-05-31 # Date range

Filtering and Exclusions

freq -x "ls,cd,pwd" # Exclude common navigation commands
freq --resolve-aliases # Resolve shell aliases
freq -c git -d week -x "git status" # Git commands this week, exclude status

Export Reports

freq -a -o report.txt # Save detailed analysis
freq -c git --timeline -o git_report.txt # Save git analysis

Advanced Combinations

# Detailed analysis with aliases resolved, excluding noise
freq -a --resolve-aliases -x "ls,cd,clear" -n 15

# Git analysis for last month with timeline and correlations
freq -c git -d month --timeline --correlations

# Today's activity excluding basic commands, save report
freq -d today -x "ls,cd,pwd,clear" -o daily_activity.txt

Command Options:

Option	Description
-n, --number	Number of top commands to show (default: 10)
-a, --advanced	Show detailed analysis with statistics
-c, --command	Analyze specific command and variations
-t, --timeline	Show usage timeline (use with -c)
-d, --date	Filter by date range (1h, 24h, week, month, year, today, YYYY-MM-DD)
-x, --exclude	Exclude commands (comma-separated)
--correlations	Show command correlations (use with -c)
--resolve-aliases	Resolve shell aliases to actual commands
-o, --output	Save output to file
-s, --shell	Specify shell type (bash, zsh, all)
-f, --file	Use custom history file
--list-files	List available history files
--debug	Show debug information

Sample Output:

Basic Analysis

Analyzed 959 commands from zsh history
 1. ls 138
 2. git 84
 3. python3 80
 4. sudo 67
 5. nano 45

Advanced Analysis

=== TOP 10 MOST USED COMMANDS ===
 1. ls (138 times)
 2. git (84 times)
 3. python3 (80 times)

=== TIME RANGE ANALYSIS ===
Data from: April 17, 2025
Data to: May 28, 2025
Total days: 42
Average commands per day: 22.8

=== COMMAND DIVERSITY ===
Unique commands: 108
Commands used only once: 42 (38.9%)

Command-Specific Analysis

=== TOP 10 'GIT' VARIATIONS ===
Total 'git' executions: 84

 1. git init (8 times)
 2. git commit -m "Initial" (8 times)
 3. git add . (7 times)
 4. git push origin main (6 times)

=== USAGE TIMELINE ===
First used: April 17, 2025 at 09:22
Last used: May 23, 2025 at 12:04
Average: 2.3 times per day over 37 days

Smart Features:

• Auto-timeline: Automatically enables timeline for development commands (git, python3, node, etc.)
• Recent activity detection: Auto-filters to last 24 hours when keywords like "today" or "recent" are detected
• Alias resolution: Finds and resolves aliases from .bashrc, .zshrc, and other config files
• Early filtering: Optimized parsing for large history files
• Cross-shell detection: Automatically detects and uses the appropriate shell history format

Requirements:

• Python 3.6+
• Linux/Unix-like system (Windows WSL supported)
• Bash or Zsh shell
• Optional: psutil package for enhanced shell detection

Supported Shells:

• Zsh - Full support including timestamped history
• Bash - Full support with and without timestamps
• Auto-detection - Automatically detects shell type and history format

History File Locations:

Zsh:

• ~/.zsh_history
• ~/.histfile
• /root/.zsh_history Bash:
• ~/.bash_history
• /root/.bash_history

Troubleshooting:

Command not found after installation

# Check if installed correctly
which freq
ls -la /usr/local/bin/freq

# If using user install, ensure PATH is set
echo $PATH | grep -o ~/.local/bin

No history found

# List available history files
freq --list-files

# Use specific file
freq -f /path/to/your/history/file

# Check your shell's history settings
echo $HISTFILE

Permission errors

# For user installation (no sudo required)
./install.sh user

# Or install to user directory manually
cp freq.py ~/.local/bin/freq

Development:

Contributing

• Fork the repository
• Create a feature branch
• Make your changes
• Test with various shell configurations
• Submit a pull request

Testing

# Test basic functionality
freq --debug
freq --list-files

# Test with different shells
freq -s bash
freq -s zsh

# Test date filtering
freq -d today --debug

Uninstall:

# Using install script
./install.sh uninstall

# Manual removal
sudo rm /usr/local/bin/freq

# User installation
rm ~/.local/bin/freq