# 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](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!

[![Production Ready](https://img.shields.io/badge/Status-Production%20Ready-brightgreen)](https://github.com/jatinmayekar/terminal-tutor)
[![Tests](https://img.shields.io/badge/Tests-116%2F116%20Passing-brightgreen)](tests/results/linux/UBUNTU_FINAL_SUCCESS_V3.md)
[![Performance](https://img.shields.io/badge/Performance-1.6ms%20avg-blue)](tests/results/linux/UBUNTU_FINAL_SUCCESS_V3.md)
[![Commands](https://img.shields.io/badge/Commands-459+-orange)](https://github.com/jatinmayekar/terminal-tutor)
[![Shell Support](https://img.shields.io/badge/Shell-Zsh%20Required-purple)](https://github.com/jatinmayekar/terminal-tutor)
[![License](https://img.shields.io/badge/License-Proprietary-red)](LICENSE)
[![Website](https://img.shields.io/badge/Website-terminaltutor.dev-green)](https://terminaltutor.dev)

## 🎯 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**

```bash
# 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)

```bash
# 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](https://terminaltutor.dev)** for:
- 🎥 **Interactive demo** - See Terminal Tutor in action
- 📊 **Premium dashboard preview** - Check out [cloud stats & leaderboard](https://terminaltutor.dev/dashboard-preview)
- 📚 **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

```bash
# 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**
```bash
# 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

```bash
# 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**
```bash
# 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**
```bash
# 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)
```bash
# 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**
```bash
# 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**
```bash
# 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](https://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`](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:

```bash
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:**
```bash
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:**
```bash
# 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):
```bash
# 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:**
```bash
# Should show tt_predict_realtime and other widgets
zle -la | grep tt_
```

**If empty, manually reload:**
```bash
# 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
- [x] **Premium Web Platform**: Cloud sync, stats dashboard, global leaderboard (LIVE!)
- [x] **Mode Systems**: `aws-mode`, `docker-mode`, `k8s-mode` for focused workflows
- [x] **Command Database**: Expanded to 459+ commands (targeting 1000+)
- [x] **Performance**: 1.4-2.0ms (exceeded target of <50ms!) ⚡
- [x] **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: jatinmayekar27@gmail.com

---

**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!