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