Commit-checker – GitHub streak tracker and offline TIL and gamified CLI tool

3 months ago 2

Keep your GitHub streak green with a lightweight, cross-platform tool.
Automatically checks your daily commits — both public (GitHub) and local (git) — with smart path detection 🧠⚙️

🎮 NEW: Gamification & Developer Progress (v0.6.0)

✅ Achievement System - Unlock badges with ASCII art (Common to Mythic rarity)
✅ XP & Level System - Earn XP from commits, progress through 10 levels
✅ Streak Tracking - Daily commit streaks with automatic achievement unlocking
✅ Visual Progress - Unicode progress bars and level-up celebrations
✅ Smart XP Calculation - Based on lines changed, deletions, and project weights
✅ Configurable Weights - Set different XP multipliers per project

📊 NEW: Advanced Analytics & Visualizations (v0.6.0)

✅ ASCII Commit Heatmap - GitHub-style activity visualization (365 days)
✅ Language Breakdown - Analyze coding languages across repositories
✅ SVG Export - Export heatmaps for sharing and documentation
✅ Dynamic Mood System - Smart status messages based on activity
✅ Visual Charts - Unicode bar charts and activity indicators

📚 NEW: TIL Vault System (v0.6.0)

✅ Template System - 5 built-in templates (bugfix, feature, concept, tool, algorithm)
✅ Individual Files - Each TIL entry as separate markdown file
✅ Fuzzy Search - Search entries with highlighted matches and scoring
✅ Auto-generation - Generate TIL entries from git commit diffs
✅ Tag Organization - Automatic tag extraction and filtering
✅ Vault Management - Comprehensive statistics and organization

✅ Smart auto-detection of git repositories
✅ Cross-platform support (macOS, Linux, Windows)
✅ Multiple development folders monitoring
✅ GitHub public & private commits tracking
✅ Repository scanning and commit analysis
✅ Most active repo detection (daily, weekly, monthly)

🧙‍♂️ Interactive Setup & Configuration

✅ Interactive Setup Wizard (--init) with guided configuration
✅ Smart Path Detection - automatically finds your dev folders
✅ Theme Selection - tech, kawaii, anime, horror, or default themes
✅ Custom Commit Rules - regex patterns for commit message validation
✅ Pre-commit Hook Installation - optional Git hook setup

📊 Enhanced Statistics & Repository Analysis

✅ ASCII Commit Charts (--stats) showing 30-day trends
✅ Visual Repository Analysis with Unicode bar charts (▁▂▃▄▅▆▇█)
✅ Multi-Repository Stats across all local repositories
✅ Recent Activity Summary with detailed commit breakdowns
✅ Repository Scanning (--scan) with commit analysis

🔍 System Diagnostics & Health

✅ System Diagnostics (--diagnose) for troubleshooting
✅ Installation Method Detection (pip, pipx, standalone)
✅ Dependency Verification and environment analysis
✅ Configuration Validation with automatic migration

🛠️ Installation & Updates

✅ No pip installation issues - works with any Python setup
✅ One-line installation with curl/bash
✅ Intelligent Update System with version caching
✅ PEP 668 Compliance - handles externally managed environments
✅ Complete uninstall functionality with smart cleanup

🚀 Quick Install (Recommended)

v0.6.1 Update: If you're experiencing uninstall issues or missing commands from v0.6.0, the latest version fixes all known issues including complete cleanup and standalone feature parity.

Method 1: Safe Installation (Recommended - avoids encoding issues)

curl -s https://raw.githubusercontent.com/AmariahAK/commit-checker/main/scripts/install-safe.sh | bash

Method 2: Manual Download (Most reliable)

curl -s https://raw.githubusercontent.com/AmariahAK/commit-checker/main/scripts/install-standalone.sh -o /tmp/install.sh chmod +x /tmp/install.sh /tmp/install.sh

Method 3: Direct Pipe (May have encoding issues on some systems)

curl -s https://raw.githubusercontent.com/AmariahAK/commit-checker/main/scripts/install-standalone.sh | bash

Method 4: Run Without Installation

curl -s https://raw.githubusercontent.com/AmariahAK/commit-checker/main/scripts/commit-checker-standalone.sh -o /tmp/commit-checker.sh chmod +x /tmp/commit-checker.sh /tmp/commit-checker.sh

Method 5: Traditional pip Install

curl -s https://raw.githubusercontent.com/AmariahAK/commit-checker/main/install.sh | bash

On first run, commit-checker intelligently detects your development setup:

🔍 Found these potential development folders: 1. Current directory: /Users/you/project (git repo) 2. /Users/you/Documents/GitHub (15 git repos found) 3. /Users/you/Developer (8 git repos found) Or enter a custom path (Default: /Users/you/Documents/GitHub) 📂 Enter number (1-3), custom path, or press Enter for default:

Basic usage:

All available commands:

Setup & Configuration:

commit-checker --init - Interactive setup wizard (recommended for first-time users)
commit-checker --setup - Quick reconfigure settings
commit-checker --diagnose - Run system diagnostics

Core functionality:

commit-checker - Check today's commits with gamification
commit-checker --scan - Scan repo folder for all git repositories
commit-checker --repos-summary - Show full summary of all repos
commit-checker --most-active - Show most active repository today
commit-checker --most-active --week - Show most active repo this week
commit-checker --most-active --month - Show most active repo this month
commit-checker --stats - Show ASCII commit trend charts (30 days)

🎮 Gamification & Progress:

commit-checker --achievements - Display achievement gallery with ASCII art
commit-checker --xp - Show current XP, level, and progress to next level
Automatic streak tracking and achievement unlocking
XP earned from commits based on lines changed and project weights

📊 Analytics & Visualizations:

commit-checker --heatmap - Display ASCII commit heatmap (365 days)
commit-checker --heatmap --days 90 - Custom timeframe heatmap
commit-checker --heatmap-export svg - Export heatmap to SVG file
commit-checker --stats-lang - Programming language breakdown with charts

📚 Enhanced TIL (Today I Learned) Vault System:

commit-checker til "Your learning today" - Add a TIL entry to log
commit-checker til "Fixed bug" --template bugfix - Use template for vault entry
commit-checker --list-templates - Show available TIL templates
commit-checker --til-vault - Show TIL vault summary with stats
commit-checker --search-til "async" - Fuzzy search TIL entries
commit-checker --til-from-diff - Generate TIL from latest commit changes
commit-checker --view-til - View your complete TIL log
commit-checker --view-til --filter-tag python - View TIL entries by tag
commit-checker --edit-til - Edit TIL log in your default editor
commit-checker --export md - Export TIL to Markdown file
commit-checker --export json - Export TIL to JSON file
commit-checker --reset-til - Clear all TIL entries (with confirmation)
commit-checker til "Entry" --no-date - Add entry without date header

System commands:

commit-checker --update - Manually check for updates
commit-checker --uninstall - Remove completely (with PEP 668 support)
commit-checker --uninstall --force - Remove without confirmation
commit-checker --support - Show support info
commit-checker --silent - Minimal output
commit-checker --nocolor - Disable emojis/colors

🌍 Cross-Platform Path Detection

macOS: ~/Documents/GitHub, ~/Developer, ~/Desktop/GitHub
Linux: ~/workspace, ~/devel, /var/www
Windows: ~/source, C:\Projects, C:\xampp\htdocs

commit-checker/ ├── 📄 LICENSE.md # MIT License ├── 📖 README.md # This file ├── 📦 setup.py # Python package setup (pip version) ├── 📋 requirements.txt # Python dependencies ├── 🚀 install.sh # Traditional pip installation ├── scripts/ # Standalone versions │ ├── 🎯 install-standalone.sh # Standalone installer │ └── 🚀 commit-checker-standalone.sh # Standalone script └── commit_checker/ # Core Python modules ├── 🔧 __init__.py # Package initialization ├── ✅ checker.py # Commit checking logic ├── ⚙️ config.py # Configuration management ├── 🔍 path_detector.py # Smart path detection └── 🔄 updater.py # Auto-update functionality

If this tool helps you stay consistent, focused, or productive — consider supporting development!

Or visit: https://buymeacoffee.com/amariahak

Amariah Kamau
📂 GitHub: @AmariahAK
🌐 Portfolio: https://portfolio-pied-five-61.vercel.app

Licensed under the MIT License.

📝 TIL (Today I Learned) Feature

Track your daily learnings with commit-checker's built-in TIL functionality:

# Add a learning entry commit-checker til "Learned how to use async/await in Python" # View your TIL log commit-checker --view-til # Edit in your preferred editor commit-checker --edit-til

# Today I Learned ## July 22, 2025 - Learned how to use async/await in Python - Discovered that Git hooks can automate code quality checks - Found out about the --no-ff flag in Git merge ## July 21, 2025 - Learned about CSS Grid layout properties - Discovered Docker multi-stage builds for smaller images

# Add entry without date grouping commit-checker til "Quick tip" --no-date # Reset all entries (with confirmation) commit-checker --reset-til

TIL Storage: Entries are saved to ~/.commit-checker/til.md and persist between sessions unless manually deleted.

$ commit-checker 🌐 GitHub: @AmariahAK 😢 No public commits found today. 🗂️ Scanning 1 local path(s): 📁 /Users/you/Documents/GitHub 🟩 Local Commits: 📁 Repository: commit-checker 📍 Path: /Users/you/Documents/GitHub/commit-checker 📊 3 commit(s) today: e05feb7 feat: implement v0.6.1 - Critical Fixes & Enhanced Reliability ⚡ 3 commits today | +2305 XP | 1🔥 streak | 🚀 Coding machine! 💫 +2305 XP earned today! 🎉 LEVEL UP! You're now level 7! 🏆 New achievements unlocked: 🟩 Hello World 🟨 Code Tsunami 🔥 Current streak: 1 days $ commit-checker --xp ⚡ Level 7: Framework Knight 💫 Total XP: 4,499 📊 Progress: [██░░░░░░░░░░░░░░░░░░] 12.5% 🎯 Next Level: 3,501 XP needed 📈 Commits Tracked: 2 $ commit-checker --achievements 🏆 Achievement Gallery ================================================== 🟩 COMMON BADGES 🟩 Hello World Made your first tracked commit 🟨 EPIC BADGES 🟨 Code Tsunami Single commit with 500+ line changes

$ commit-checker --heatmap 📅 Commit Heatmap (Last 365 days) ================================================== 01/28: ░ ░ ░ ░ ░ ░ ░ 02/04: ░ ░ ░ ░ ░ ░ ░ ... 07/20: ░ ▓ ▒ ▒ ▒ ▒ ░ 07/27: ▓ █ ▓ ▒ ░ ░ ░ Legend: ░ None ▒ Low ▓ Medium █ High Max commits in a day: 5 Last 7 days: 12 commits $ commit-checker --stats-lang 📊 Programming Language Breakdown ================================================== Python [████████████████░░░░░░░░░░░░░░] 54.1% (3,274 lines, 47 files) JavaScript [███████░░░░░░░░░░░░░░░░░░░░░░░] 23.2% (1,405 lines, 23 files) TypeScript [████░░░░░░░░░░░░░░░░░░░░░░░░░░] 13.1% (793 lines, 12 files) CSS [██░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 6.8% (412 lines, 8 files) Markdown [█░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 2.8% (169 lines, 5 files) 📈 Total: 6,053 lines across 95 files

$ commit-checker --list-templates 📚 Available TIL templates: • algorithm • bugfix • concept • feature • tool Usage: commit-checker til "Title" --template algorithm $ commit-checker til "Fixed async race condition" --template bugfix TIL created: /Users/you/.commit-checker/tils/2025-07-28-fixed-async-race-condition.md $ commit-checker --til-vault 📚 TIL Vault Summary ================================================== 📁 Location: /Users/you/.commit-checker/tils/ 📄 Total entries: 5 📝 Recent entries: • 2025-07-28: Fixed async race condition #bugfix #async • 2025-07-27: Implemented new caching layer #feature #performance • 2025-07-26: Understanding Docker volumes #concept #docker 🏷️ Popular tags: #bugfix (2) #feature (1) #concept (1) $ commit-checker --search-til "async" 🔍 Found 2 TIL entries: ================================================== 1. 📝 Fixed async race condition 📅 2025-07-28 | Score: 10 L1: # Fixed async race condition L15: - Used asyncio.Lock() to prevent race conditions 2. 📝 Understanding async patterns 📅 2025-07-26 | Score: 5 L8: - async/await syntax in Python

$ commit-checker --init 🧙‍♂️ Welcome to commit-checker Interactive Setup Wizard! 🌐 GitHub Configuration 👤 GitHub username: AmariahAK 📁 Development Folder Configuration 🔍 Found these potential development folders: 1. /Users/you/Documents/GitHub (15 git repos found) 2. /Users/you/Developer (8 git repos found) 🎨 Output Style Configuration 1. 🎉 Emoji mode (colorful with emojis) 2. 📝 Plain mode (simple text only) 📚 TIL Configuration... 🎉 Configuration saved!

$ commit-checker --stats 📊 Commit Statistics (Last 30 Days) ================================================== 📁 commit-checker Total commits: 18 Trend: ▁▂▃█▇▆▅▃▂▁▃▄▅▇█▇▅▃▂▁▂▄▅▆▇█▇▅▃▂▁ Recent: 2025-07-23: 2, 2025-07-24: 3, 2025-07-25: 5 📁 my-website Total commits: 12 Trend: ▁▁▂▃▄▅▆▇█▇▆▅▄▃▂▁▁▂▃▄▅▆▇█▇▆▅▄▃▂▁ Recent: 2025-07-23: 1, 2025-07-24: 2, 2025-07-25: 4

$ commit-checker til "Learned about async/await in Python" --tag python ✅ TIL entry added (tagged: python) $ commit-checker --view-til --filter-tag python # Today I Learned ## July 25, 2025 - Learned about async/await in Python `#python` - Python decorators can modify function behavior `#python` $ commit-checker --export json 📊 TIL exported to ~/til_export_20250725_143022.json

$ commit-checker --diagnose 🔍 System Diagnostics ============================== 🐍 Python version: 3.11.5 📦 Git: git version 2.39.0 📦 Package: Installed via pip (v0.5.0) ⚙️ Config: Found at ~/.commit-checker/config.json GitHub user: AmariahAK Local paths: 2 configured Output mode: emoji 📚 Dependencies: ✅ requests: Available ✅ packaging: Available ✅ colorama: Available 🐍 Environment: Virtual environment 📦 pipx: Available but commit-checker not installed via pipx ✅ Diagnostics complete!

v0.6.1 - Critical Fixes & Enhanced Reliability (Latest)

🚨 Complete Uninstallation - Fixed --uninstall leaving shell startup commands, now removes ALL traces
🛡️ Bulletproof Wizard - Enhanced --init validation prevents invalid input choices with clear error messages
🔍 Improved Detection - Fixed duplicate repository paths and enhanced counting accuracy in setup
⚡ Standalone Completeness - Added ALL missing commands (--achievements, --xp, --heatmap, etc.) to curl version
✨ Better UX - Instant theme feedback, robust input validation, and enhanced error handling

v0.6.0 - Offline Gamified Power Mode

🎮 Complete Gamification - Achievement system with ASCII art, XP levels, streak tracking
📊 Advanced Analytics - ASCII heatmaps, language breakdown, SVG export, mood system
📚 TIL Vault System - Templates, fuzzy search, auto-generation from diffs, individual files
⚡ Offline-First Architecture - Zero external dependencies, pure git-powered analytics
🔧 Developer-Friendly Hooks - Non-blocking git hooks for seamless integration
🛠️ 15+ New Commands - Comprehensive CLI with gamification, analytics, and vault features

v0.5.0 - Interactive Wizards & Enhanced Analytics

🧙‍♂️ Interactive Setup Wizard - Complete guided configuration with --init
📊 ASCII Statistics - Visual commit trends and repository analytics
📚 Enhanced TIL System - Tags, filtering, and export functionality
🔍 System Diagnostics - Comprehensive health checks and troubleshooting
🔧 Critical Bug Fixes - Fixed update loops and PEP 668 uninstall issues

v0.4.3 - TIL (Today I Learned) Feature

📝 New TIL Command - Log daily learnings with commit-checker til "message"
📁 Local Storage - Entries saved to ~/.commit-checker/til.md with smart date organization
🖊️ Editor Integration - --edit-til opens your TIL log in default editor
👀 View & Reset - --view-til and --reset-til for easy management
🔧 Customizable - Configure TIL path via config.json

v0.4.2 - Enhanced Update System

🔄 Intelligent Update Scheduling - Install updates now or on next terminal restart
📋 Release Notes Preview - See what's new before updating
🔧 Robust Update Methods - Multiple fallback installation approaches
📅 Pending Update Management - Automatic installation of scheduled updates

v0.4.1 - Advanced Repository Analytics

🔍 Repository scanning with --scan flag
📊 Complete repo summaries with commit statistics
🔥 Most active repo detection (daily, weekly, monthly)
🎨 Configurable output modes (emoji or plain text)
🗑️ Enhanced uninstall with --force option
⚙️ Persistent configuration with repo folder settings

v0.2.0 - Smart Detection & Standalone Support

🔍 Smart auto-detection of git repositories
🌍 Enhanced cross-platform support
📁 Multiple path monitoring
🚀 Standalone bash version (no pip issues!)
🛠️ Improved setup experience

✅ Basic GitHub and local commit tracking
🎛️ CLI interface with multiple flags
🔄 Auto-update functionality

Read Entire Article