Your Terminal Journey Companion - Track, Gamify, and Level Up Your CLI Productivity
🚀
/|\
/ | \
| T |
| |
|| ||
/\ /\
Termonaut is a lightweight, privacy-focused terminal productivity tracker that gamifies your command-line experience. Transform your daily shell usage into an engaging RPG-like journey with XP, levels, badges, and shareable stats—all without leaving your terminal.
termonaut setup - Guided configuration for new userstermonaut quickstart - One-command setup with sensible defaultstermonaut tui - Automatically adapts to your terminal size (default)termonaut tui --mode compact - Efficient layout for smaller terminalstermonaut tui --mode full - Immersive experience for wide terminalstermonaut stats - Lightning-fast shell outputtermonaut alias commands for easy ‘tn’ shortcut managementtermonaut tui)tn instead of termonaut for all commandsVisit our geek-style homepage at: https://oiahoon.github.io/termonaut
The homepage features:
# Start local development server
./scripts/dev-homepage.sh
# Deploy homepage (maintainers only)
./scripts/deploy-homepage.sh
🎯 Latest Optimized Version (v0.9.4+)
Features enhanced performance, comprehensive testing, and modular architecture
GitHub Install (Recommended):
# Install from GitHub releases
curl -sSL https://raw.githubusercontent.com/oiahoon/termonaut/main/install.sh | bash
Homebrew Installation:
# Install from our custom tap
brew tap oiahoon/termonaut
brew install termonaut
# Or install from homebrew-core (coming soon!)
brew install termonaut
Manual Installation:
# Download latest release for your platform
# Linux (x64)
wget https://github.com/oiahoon/termonaut/releases/latest/download/termonaut-linux-amd64
chmod +x termonaut-linux-amd64
sudo mv termonaut-linux-amd64 /usr/local/bin/termonaut
# macOS (Intel)
wget https://github.com/oiahoon/termonaut/releases/latest/download/termonaut-darwin-amd64
chmod +x termonaut-darwin-amd64
sudo mv termonaut-darwin-amd64 /usr/local/bin/termonaut
# macOS (Apple Silicon)
wget https://github.com/oiahoon/termonaut/releases/latest/download/termonaut-darwin-arm64
chmod +x termonaut-darwin-arm64
sudo mv termonaut-darwin-arm64 /usr/local/bin/termonaut
Build from Source:
git clone https://github.com/oiahoon/termonaut.git
cd termonaut
go build -o termonaut cmd/termonaut/*.go
sudo mv termonaut /usr/local/bin/
🆕 New User? Start Here:
Interactive Setup (Recommended):
termonaut setup
# Guided configuration with explanations
Quick Setup:
termonaut quickstart
# One-command setup with sensible defaults
Manual Setup:
termonaut init
# Install shell integration manually
This automatically adds hooks to your ~/.bashrc or ~/.zshrc. Restart your terminal or run:
source ~/.bashrc # or ~/.zshrc
💡 Pro Tip: Use tn as a short alias for termonaut in all commands!
📖 Need detailed setup help? Check our Quick Start Guide for step-by-step instructions!
View Your Stats:
termonaut stats # Today's overview (minimal mode)
termonaut stats --weekly # This week's stats
termonaut stats --monthly # This month's statistics
# Or use the short alias:
tn stats # Today's overview
tn stats --weekly # This week's stats
tn stats --monthly # This month's statistics
Interactive Dashboard:
termonaut tui # Smart mode (adapts to terminal size)
termonaut tui --mode compact # Compact mode for smaller terminals
termonaut tui --mode full # Full mode for wide terminals
termonaut tui --mode minimal # Text-only stats output
# Short commands:
tn tui # Smart mode dashboard
tn tui -m compact # Compact mode
tn tui -m full # Full mode
Avatar System:
# Avatar system is integrated into TUI and stats display
# Avatar management via configuration:
termonaut config set avatar_style pixel-art # Change avatar style
termonaut config set avatar_size large # Set avatar size preference
# Short commands:
tn config set avatar_style bottts # Change to robot style
tn config get avatar # View avatar settings
Alias Management:
termonaut alias info # Show alias information and status
termonaut alias check # Check if 'tn' alias exists
termonaut alias create # Create 'tn' shortcut manually
termonaut alias remove # Remove 'tn' alias
# Short commands:
tn alias info # Show alias information
tn alias check # Check alias status
Configuration:
termonaut config set theme emoji # Enable emoji theme
termonaut config set gamification true # Toggle XP system
termonaut config get # View all settings
# Short commands:
tn config set theme emoji # Enable emoji theme
tn config set gamification true # Toggle XP system
tn config get # View all settings
Data Management:
# Data export/import features are planned for future release
# Current data location: ~/.termonaut/termonaut.db
# Manual backup: cp ~/.termonaut/termonaut.db ~/backup/
# Advanced data operations:
termonaut advanced bulk --help # Bulk operations on command data
termonaut advanced filter --help # Advanced filtering and search
$ termonaut stats --today
🚀 Today's Terminal Stats (2024-01-15)
─────────────────────────────────────
Commands Executed: 127 🎯
Active Time: 3h 42m ⏱️
Session Count: 4 📱
New Commands: 3 ⭐
Current Streak: 12 days 🔥
Top Commands:
git (23) ████████████████████████████████
ls (18) ███████████████████████████
cd (15) ██████████████████████
vim (12) ████████████████
🎮 Level 8 Astronaut (2,150 XP)
Progress to Level 9: ████████████░░░░ 75%
Termonaut uses a TOML configuration file at ~/.termonaut/config.toml:
# Display and Theme
display_mode = "enter" # Options: off, enter, ps1, floating
theme = "emoji" # Options: minimal, emoji, ascii
show_gamification = true # Enable XP and leveling system
# Tracking Behavior
idle_timeout_minutes = 10 # Session timeout
track_git_repos = true # Include git repository context
command_categories = true # Categorize commands automatically
# GitHub Integration (Optional)
sync_enabled = false # Enable GitHub sync
sync_repo = "username/termonaut-profile"
badge_update_frequency = "daily"
# Privacy
opt_out_commands = ["password", "secret"] # Commands to ignore
anonymous_mode = false # Strip personal paths from logs
Unlock 20+ badges as you progress:
| Badge | Description | Criteria |
|---|---|---|
| 🚀 First Launch | Welcome aboard! | Execute your first command |
| 🌟 Explorer | Command discoverer | Use 50 unique commands |
| 🏆 Century | Daily powerhouse | 100 commands in one day |
| 🔥 Streak Keeper | Consistency master | 7-day usage streak |
| 👨🚀 Space Commander | Terminal veteran | Reach level 10 |
| 🪐 Cosmic Explorer | Universe navigator | 30-day usage streak |
| ⚡ Lightning Fast | Speed demon | 500 commands in one day |
| 🛸 Master Navigator | Elite astronaut | Reach level 25 |
| 🏃♂️ Shell Sprinter | Speed demon | Execute commands rapidly |
| 🧙♂️ Config Whisperer | Configuration master | Edit config files frequently |
| 🌙 Night Coder | Night owl | Code during late hours |
| 🧬 Git Commander | Version control expert | Master git operations |
| 🔥 Pro Streaker | Consistency champion | Maintain long streaks |
| 🛡️ Sudo Smasher | Admin privileges user | Use sudo commands |
| 🐳 Docker Whale | Container expert | Work with Docker |
| 🎭 Vim Escape Artist | Editor ninja | Master vim commands |
| 💪 Error Survivor | Resilience master | Handle command failures |
View all achievements with tn tui and navigate to the Achievements tab!
Automatically sync your terminal stats to GitHub and display dynamic badges:
# Interactive setup (recommended)
termonaut github sync setup
# Or manual configuration:
termonaut config set sync_enabled true
termonaut config set sync_repo username/termonaut-profile
termonaut config set badge_update_frequency daily
# Manual sync (immediate)
termonaut github sync now
# Check sync status
termonaut github sync status
# View available commands
termonaut github --help
# Generate all badges
termonaut github badges generate
# Generate profile
termonaut github profile generate
# Setup GitHub Actions for automation
termonaut github actions generate termonaut-stats-update
Add your stats to your shell prompt:
# Add to ~/.bashrc or ~/.zshrc
export PS1="$(termonaut prompt) $PS1"
Advanced data operations:
termonaut advanced analytics --help # Advanced analytics features
termonaut advanced api --help # API server for integrations
termonaut github sync --help # GitHub integration features
~/.termonaut/
├── config.toml # User configuration
├── termonaut.db # SQLite database
├── termonaut.log # Application logs
├── cache/
│ ├── export.json # Latest export data
│ └── badges/ # Generated badge files
└── backups/ # Automatic daily backups
We welcome contributions! Please see our Development Guide for:
git clone https://github.com/oiahoon/termonaut.git
cd termonaut
make dev-setup # Install dependencies and dev tools
make test # Run test suite
make build # Build binary
See our Project Planning for detailed milestones.
MIT License - see LICENSE for details.
“Hack your habits from the shell.” 🚀
Transform your terminal from a tool into an adventure. Every command is a step toward mastery.
For detailed documentation, visit our Wiki or run termonaut help.