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

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