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

## 🎯 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
- ✅ **macOS/Linux** - Native Unix support
- ✅ **Windows** - Via Git Bash or WSL2 (native PowerShell coming 2026)

### **Step 1: Check if you have Zsh installed**

```bash
# Check if Zsh is installed:
which zsh

# ✅ If it shows: /bin/zsh or /usr/bin/zsh → Zsh is installed! Go to Step 2
# ❌ If it shows: nothing or "zsh not found" → Install Zsh in Step 2
```

### **Step 2: Install Zsh (if needed)**

```bash
# macOS (Zsh pre-installed on macOS 10.15+)
# Skip to Step 3!

# Ubuntu/Debian/Linux Mint
sudo apt update && sudo apt install zsh

# Fedora/RHEL/CentOS
sudo dnf install zsh

# Arch Linux
sudo pacman -S zsh
```

### **Step 3: Switch to Zsh**

**Option A: Try Zsh NOW (temporary - recommended for testing)**
```bash
zsh
# ↑ You're now in Zsh! Perfect for testing Terminal Tutor.
# To exit Zsh and return to your previous shell, type: exit
```

**Option B: Make Zsh your DEFAULT shell (permanent)**
```bash
chsh -s $(which zsh)
# ⚠️ Will ask for your password (your macOS/Linux login password - this is normal!)
# ℹ️ If you see "no changes made" → You're already on Zsh! Success!
# Close terminal and reopen → You'll be in Zsh automatically

# Verify it worked:
echo $SHELL  # Should show: /bin/zsh
```

**💡 Recommended:** Try Option A first to test Terminal Tutor, then use Option B to make it permanent if you like it!

## 🚀 **Quick Start** (2 minutes to awesome)

**Step 1: Install with uv (recommended)**
```bash
# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Terminal Tutor with uv
uv tool install terminal-tutor
```

**Alternative: Install with pipx**
```bash
# If you prefer pipx
pipx install terminal-tutor
```

**Step 2: Activate real-time predictions**
```bash
# Activate the magic (adds to ~/.zshrc)
terminal-tutor install

# Restart Zsh to load integration
exec zsh
```

**Step 3: Test it works!**
```bash
# Start typing slowly... watch predictions appear!
git st█
# You should see: 🟢 SAFE - Show working tree status

# Verify installation
terminal-tutor status
# Should show: 🟢 Enabled
```

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

## 🎭 **Shell Support**

### **Zsh** - Real-Time Predictions (REQUIRED for now)
```bash
# ✅ FULLY SUPPORTED: Real-time predictions with ZLE widgets
# Type naturally, see descriptions instantly (1.4-2.0ms)
# Zero configuration after installation
# This is the ONLY way to experience real-time Terminal Tutor
```

### **Bash & Fish** - Coming Soon
```bash
# ⏳ PLANNED: Real-time support in future releases
# Currently, use Zsh for the full experience
# Bash/Fish users: Install Zsh to use Terminal Tutor
```

## 🎮 **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)

**Documentation**: See [tests/results/linux/UBUNTU_FINAL_SUCCESS_V3.md](tests/results/linux/UBUNTU_FINAL_SUCCESS_V3.md) for detailed test reports.

## 🛠️ **Installation & Setup**

### **System Requirements**
- ✅ **Zsh shell** - REQUIRED (Bash/Fish not supported yet)
- ✅ **Python 3.7-3.13** - Runtime environment
- ✅ **macOS/Linux** - Native Unix support
- ✅ **Windows** - Via Git Bash or WSL2 (native PowerShell coming 2026)
- ✅ **uv or pipx** - Recommended installation tool

### **Production Installation (Recommended)**
```bash
# Method 1: Using uv (fastest, recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install terminal-tutor
terminal-tutor install
exec zsh

# Method 2: Using pipx
pipx install terminal-tutor
terminal-tutor install
exec zsh

# Verify it works
terminal-tutor status  # Should show: 🟢 Enabled
```

### **Development Installation**
```bash
# Clone repository
git clone https://github.com/jatinmayekar/terminal-tutor.git
cd terminal-tutor

# Install in editable mode
uv tool install --editable .
# OR: pipx install --editable .

# Activate
terminal-tutor install
exec zsh

# Test with debug mode
terminal-tutor debug "git"  # Shows performance metrics
```

## 🌍 **Community & Contribution**

### **Join the Revolution**
- 🌟 **Star us** on GitHub to support development
- 🐛 **Report issues** to help us improve
- 💡 **Suggest features** for future releases
- 📚 **Contribute commands** to expand the database

### **Developer Resources**
- **Documentation**: Complete agent onboarding in `CLAUDE.md`
- **Strategy Docs**: Business strategy and ICP analysis in `docs/strategy/`
- **Deployment Guides**: Production deployment in `docs/deployment/`
- **Research**: Algorithm analysis in `docs/research/`
- **Launch Content**: Marketing content and launch plan in `docs/launch/`
- **Testing**: Beta testing strategy in `evaluation/` folder
- **Roadmap**: Future plans in `TODO.md`

## 🗺️ **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

## 📈 **Success Metrics**

Terminal Tutor has achieved **production excellence** across all key metrics:

- ✅ **Performance**: 1.4-2.0ms prediction time (96% faster than target!)
- ✅ **Testing**: 116/116 tests passing (100% success rate)
- ✅ **Accuracy**: 100% precision on critical test cases
- ✅ **Coverage**: 459+ commands across major developer tools
- ✅ **Reliability**: Zero-downtime shell integration
- ✅ **User Experience**: Silent operation with action-first UX

## 🏆 **Awards & Recognition**

- **🥇 World's First**: Real-time command education tool
- **⚡ Performance Leader**: 1.4-2.0ms prediction times (96% faster than target)
- **✅ Quality Assurance**: 116/116 tests passing (100% success rate)
- **🧠 Algorithm Innovation**: FZF-inspired exponential position decay
- **🛡️ Safety Pioneer**: Context-aware risk assessment
- **👥 Developer Choice**: Zero-configuration, maximum value

## 🔒 **Security & Privacy**

- **Local Processing**: Commands never leave your machine
- **No Telemetry**: Your workflow stays private
- **Safe Execution**: Commands run only with your explicit approval
- **Code Transparency**: Source code available for review

## 📄 **License**

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

For commercial licensing: jatin@terminaltutor.dev

---

## 🚀 **Ready to Transform Your Terminal Experience?**

```bash
# Requirements: Zsh shell + macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install terminal-tutor
terminal-tutor install
exec zsh
# Welcome to the future of command-line learning! ✨
```

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