terminal-tutor 0.1.14

Real-time terminal command education for Zsh - 1.6ms avg predictions, 459+ commands, 100% tested (Zsh required)

Terminal Tutor 🚀

⚖️ License Notice: Terminal Tutor is proprietary software. Personal, non-commercial use permitted. Commercial/enterprise use requires a paid license. Unauthorized distribution or modification may result in legal action including statutory damages up to $150,000 per violation. See LICENSE file for full terms.

World's first real-time command education tool - Learn terminal commands as you type with instant descriptions, safety warnings, and intelligent suggestions!

🎯 What Makes Terminal Tutor Revolutionary?

Terminal Tutor is the first and only terminal education tool that provides real-time command descriptions as you type - literally keystroke by keystroke. No more waiting, no more guessing, no more dangerous mistakes.

⚡ Real-Time Magic in Action

# As you type "git st" - predictions appear instantly:
$ git st█                           # ← You're typing here
🟢 SAFE - Show working tree status   # ← Live prediction appears below

Performance: 1.4-2.0ms response time (96% faster than target!) ⚡

⚠️ Requirements - Install Zsh First!

REQUIRED:

• ✅ Zsh shell - Real-time predictions ONLY work in Zsh (Bash/Fish not supported yet)
• ✅ Python 3.7+ - Python runtime required

🔥 Installation (Ubuntu/Debian - 30 seconds)

# Step 1: Install dependencies
apt-get update && apt-get install -y zsh python3 python3-pip pipx netcat-openbsd

# Step 2 (Optional): Install Oh-My-Zsh for enhanced experience
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" "" --unattended

# Step 3: Switch to Zsh & Install Terminal Tutor
zsh
pipx install terminal-tutor
export PATH="$PATH:$HOME/.local/bin"

# Step 4: Setup (auto-starts daemon for instant predictions)
terminal-tutor install
exec zsh

# Step 5: Try it!
git st  # Type slowly, watch prediction appear instantly

That's it! Real-time predictions should now appear as you type.

---

🌐 Want to Learn More?

Visit terminaltutor.dev for:

• 🎥 Interactive demo - See Terminal Tutor in action
• 📊 Premium dashboard preview - Check out cloud stats & leaderboard
• 📚 Full documentation - Complete feature showcase
• 💰 Pricing & plans - Free tier & Premium features
• 🏆 Community resources - Join the terminal revolution

---

You're now a command-line wizard! ✨

🌟 Core Features

🔮 Real-Time Predictions (Zsh - World First!)

• Keystroke-by-keystroke command education
• 1.4-2.0ms lightning-fast response time (avg 1.6ms)
• Live descriptions appear as you type
• Zero latency user experience

🧠 Intelligent Fuzzy Matching

• State-of-the-art algorithm with exponential position decay
• Surgical precision - no irrelevant suggestions
• Context-aware recommendations
• FZF-inspired smart scoring

# Smart suggestions for partial input (use debug for performance metrics)
$ terminal-tutor debug "git s"
───────────────────────────────────
🟢 SAFE git status - Show the working tree status
🟡 CAUTION git stash - Stash changes in a dirty working directory
🟢 SAFE git show - Show various types of objects
───────────────────────────────────
⏱️  1.2ms | 📊 3 matches | 🔍 fuzzy

🗣️ Natural Language Command Discovery

# Ask in plain English, get exact commands
$ terminal-tutor ask "how to list files"
ls - 🟢 SAFE - List directory contents

$ terminal-tutor ask "copy files recursively"
cp -r - 🟢 SAFE - Copy directories recursively

First-time setup: The ask mode requires an OpenAI API key. On first use, you'll be prompted to enter your key. Get one here: https://platform.openai.com/api-keys

# Configure API key manually
$ terminal-tutor config api-key set

# Check API key status
$ terminal-tutor config api-key status

# Remove stored API key
$ terminal-tutor config api-key clear

Security: API keys are stored in ~/.terminal_tutor_openai_key with 600 permissions (user read/write only) and never echoed to the terminal.

🛡️ Advanced Safety System

• 🟢 SAFE / 🟡 CAUTION / 🔴 DANGEROUS risk levels
• Smart pattern recognition for destructive commands
• Context-aware warnings with safety prompts
• False positive elimination through machine learning

📚 Comprehensive Command Database (459+ commands)

• Git: Complete workflow coverage (13 commands)
• Docker: Container lifecycle management (15 commands)
• Kubernetes: Cluster operations (13 commands)
• AWS CLI: Full cloud platform coverage (96 commands)
• System Commands: Unix/Linux essentials (41+ commands)
• Network Tools: Connectivity and security (45+ commands)

🎮 Usage Examples

Daily Development Workflow

# Git operations with confidence
$ git rebase -i HEAD~3█
🟡 CAUTION - Interactively rebase commits (can rewrite history)

# Docker deployments made safe
$ docker rm -f $(docker ps -aq)█
🔴 DANGEROUS - Force remove ALL containers (data loss risk)

# Kubernetes with clarity
$ kubectl delete deployment nginx█
🟡 CAUTION - Delete deployment (will terminate all pods)

Learning New Tools

# Explore AWS services with debug (shows performance metrics)
$ terminal-tutor debug "aws s3"
───────────────────────────────────
🟢 SAFE aws s3 ls - List S3 buckets or objects
🟢 SAFE aws s3 cp - Copy files to/from S3
🟡 CAUTION aws s3 sync - Sync directories with S3
───────────────────────────────────
⏱️  1.1ms | 📊 3 matches | 🎯 exact (+ related)

# Discover system commands
$ terminal-tutor ask "monitor system resources"
htop - 🟢 SAFE - Interactive process viewer

⚙️ Advanced Management

Debug Command (New - Unified Diagnostic Tool)

# Debug with performance metrics - shows timing, match count, and match type
terminal-tutor debug "git"           # Top 3 matches + performance stats
terminal-tutor debug "git status"    # Exact match + timing
terminal-tutor debug "c"             # Fuzzy matching + metrics

# Example output:
───────────────────────────────────
🟢 SAFE git - Distributed version control system
🟢 SAFE git add - Add file contents to the index
🟢 SAFE git log - Show commit logs
───────────────────────────────────
⏱️  1.2ms | 📊 3 matches | 🎯 exact (+ related)

Note: explain and suggest commands are deprecated - use debug instead.

Control Commands

# Instant control
terminal-tutor disable   # Pause predictions
terminal-tutor enable    # Resume magic
terminal-tutor toggle    # Smart toggle
terminal-tutor status    # Check state

# Usage insights
terminal-tutor usage     # View daily stats
terminal-tutor premium   # Upgrade options

# Configuration
terminal-tutor config api-key set      # Configure OpenAI API key
terminal-tutor config api-key status   # Check API key status
terminal-tutor config api-key clear    # Remove stored API key

Custom Commands

# Add your own commands to Terminal Tutor
# Create ~/.terminal_tutor_custom_commands.json

{
  "version": "1.0",
  "commands": {
    "deploy-prod": {
      "description": "Deploy to production environment",
      "risk_level": "DANGEROUS",
      "category": "custom"
    },
    "my-build": {
      "description": "Custom build script for my project",
      "risk_level": "SAFE",
      "category": "custom"
    }
  }
}

# Your custom commands will:
# - Override default commands (if same name)
# - Appear in fuzzy search results
# - Work with real-time predictions
# - Show correct risk levels

# Edit default commands database:
# terminal_tutor/data/commands.json (459+ commands)

💎 Premium Features

Free Tier - Forever Free

• Unlimited real-time predictions in Zsh
• Complete command database (459+ commands, growing to 1000+)
• All safety warnings and command descriptions
• BYO API key for ask mode (use your own OpenAI key)
• Local LLM support (Ollama integration)
• 7-day local stats history

Premium Tier - $7/month ✨ NOW AVAILABLE

• Zero-setup AI - No API key configuration needed
• Cloud-synced stats - Access from any device with MongoDB Atlas
• Developer leaderboard - See how you rank globally among developers
• Stats dashboard - Track command usage, learning streaks, favorite commands
• Team libraries - Shared command definitions
• Priority support - Direct developer access
• Career stats export - LinkedIn/resume-ready metrics

🌐 Preview the Premium Dashboard: Visit terminaltutor.dev/dashboard-preview to see what Premium offers!

Web Platform Architecture

The Premium tier is powered by a production-ready web platform:

• Frontend/Backend: Next.js 15 with App Router (deployed on Vercel)
• Database: MongoDB Atlas (cloud-synced user stats and command history)
• Authentication: NextAuth v5 with Google OAuth
• API Routes: RESTful endpoints for stats sync and leaderboard
• Dashboard Components: Real-time stats visualization with DaisyUI

For deployment documentation, see docs/deployment/DEPLOYMENT_GUIDE.md

🧪 Technical Excellence

Performance Benchmarks

• Prediction Time: 1.4-2.0ms avg (target: <50ms) ✅ 96% faster!
• Test Results: 116/116 tests passing across Ubuntu 22.04/24.04 ✅
• Algorithm Precision: 100% on critical test cases ✅
• Memory Usage: Minimal footprint with intelligent caching
• Startup Time: Zero-latency shell integration

Architecture Highlights

• O(1) prefix tree lookup for instant command matching
• Exponential position decay for fuzzy search precision
• File-based controls for real-time performance
• Graceful degradation when offline or under load

Quality Standards

• Security First: No credential exposure, safe execution
• Backward Compatibility: Seamless upgrades
• Shell Agnostic: Works across Unix/Linux environments
• Silent Operation: No noise, action-first UX

Platform Compatibility

Platform	Status	Tests	Performance	Notes
Ubuntu 22.04 (Zsh)	✅ Verified	29/29	1.7-1.8ms	100% pass rate
Ubuntu 22.04 + Oh-My-Zsh	✅ Verified	29/29	1.7ms	Full compatibility
Ubuntu 24.04 (Zsh)	✅ Verified	29/29	1.4ms	⚡ Fastest
Ubuntu 24.04 + Oh-My-Zsh	✅ Verified	29/29	1.5ms	Full compatibility
macOS (Zsh)	✅ Working	-	2.0ms	Core functionality verified
WSL2 (Ubuntu)	🟡 Expected	-	-	Should work (Ubuntu compat)
PowerShell	🚧 Planned	-	-	Coming 2026

Total Tests: 116/116 passing (100% success rate)

Troubleshooting

🔍 Automated Diagnostics (Recommended First Step)

If you're experiencing installation or real-time prediction issues, run the automated diagnostic tool:

terminal-tutor diagnose

This will check:

• ✅ Shell compatibility (Zsh required for real-time)
• ✅ Integration installed in shell config
• ✅ ZLE widgets registered
• ✅ Keybindings set correctly
• ✅ Command functionality
• ✅ Performance metrics

Example output:

🔍 Terminal Tutor Diagnostic Report
════════════════════════════════════

✅ Shell Check: Using Zsh (real-time predictions supported)
✅ Installation Check: Integration found in ~/.zshrc
❌ ZLE Widgets: No ZLE widgets registered (0/5)

🔧 Recommended Fixes:
  ZLE Widgets:
    1. Restart shell: exec zsh
    2. Source config manually: source ~/.zshrc
    3. If still broken, reinstall: terminal-tutor install --force

For detailed diagnostics:

terminal-tutor diagnose --verbose

---

"command not found: terminal-tutor" after pip install

If you installed with pip install terminal-tutor (instead of uv or pipx) and see this error, the installation directory may not be in your PATH.

Quick Fix:

# Add ~/.local/bin to PATH temporarily
export PATH="$HOME/.local/bin:$PATH"

# Test it works now
terminal-tutor status

# Make it permanent by adding to ~/.zshrc
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Better Solution - Use uv or pipx (handles PATH automatically):

# Uninstall pip version
pip uninstall terminal-tutor

# Reinstall with uv (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install terminal-tutor

Why this happens: When using pip install --user, Python installs to ~/.local/bin, which may not be in your default PATH on some systems.

---

Real-time predictions not working after install

If terminal-tutor install succeeds but real-time predictions don't appear when typing:

Check if integration loaded:

# Should show tt_predict_realtime and other widgets
zle -la | grep tt_

If empty, manually reload:

# Find the integration file
find /usr -name "zsh_integration.zsh" 2>/dev/null

# Source it (use the path from above)
source /usr/local/lib/python3.12/dist-packages/terminal_tutor/zsh_integration.zsh

# Or reinstall
terminal-tutor install
exec zsh

Why this happens: In some environments (Docker, fresh installs), the shell config file may not exist or the SHELL environment variable may not be set correctly. The latest version creates the file automatically.

🗺️ Roadmap 2024-2025

Phase 2: Platform Expansion ✅ Mostly Complete

• Premium Web Platform: Cloud sync, stats dashboard, global leaderboard (LIVE!)
• Mode Systems: aws-mode, docker-mode, k8s-mode for focused workflows
• Command Database: Expanded to 459+ commands (targeting 1000+)
• Performance: 1.4-2.0ms (exceeded target of <50ms!) ⚡
• Testing: 116/116 tests passing on Ubuntu 22.04/24.04 ✅
• Windows PowerShell: Full Windows environment support

Phase 3: Ecosystem Growth

• VS Code Extension: Integrated terminal support
• Team Features: Shared command libraries and custom definitions
• Community Platform: User-contributed command database
• Enterprise Features: RBAC, audit trails, compliance reporting

Phase 4: AI Integration

• Advanced ML: Context-aware safety assessment
• Learning Analytics: Personalized command recommendations
• Intelligent Completion: Predictive command finishing
• Natural Language: Enhanced conversational interface

📄 License

Proprietary License - Personal, non-commercial use permitted. Enterprise/commercial use requires paid license.

For commercial licensing: [e-mail]

---

Made with ❤️ by developers, for developers who refuse to settle for outdated tools.

---

⭐ Star us on GitHub if Terminal Tutor revolutionizes your workflow! 🔄 Share with your team - spread the command-line revolution! 💬 Join our community - help shape the future of terminal education!