EnhancedTerminal/USAGE_GUIDE.md

# Enhanced Terminal v3.0 - Usage Guide

## 🎯 Quick Start

1. **Build the application:**
   ```bash
   ./build.sh
   ```

2. **Launch the terminal:**
   ```bash
   open EnhancedTerminal.app
   ```

3. **Start using it!** The terminal works just like your regular terminal, but with superpowers.

## 🌟 Key Features

### 1. Command History Search (Cmd+R)

The most powerful feature for productivity!

**How to use:**
1. Press `Cmd+R` to open the history search panel
2. Start typing to search through your command history
3. The search is **fuzzy** - it finds commands containing your search terms
4. Double-click a command or press Enter to use it
5. The command is inserted at your cursor position

**Example:**
- Type "docker" to find all docker-related commands
- Type "git commit" to find all git commit commands
- Type "find pdf" to find commands that searched for PDFs

**Tips:**
- History is saved between sessions
- Recent commands appear first
- Search is case-insensitive

### 2. Auto-Suggestions (Like Fish Shell)

As you type, the terminal suggests commands from your history.

**How it works:**
1. Start typing a command
2. If you've used a similar command before, it appears in gray text
3. Press `Tab` to accept the suggestion
4. Continue typing to ignore it

**Example:**
```
$ git st█
      status  ← suggestion appears in gray
```
Press Tab to complete to `git status`

**Toggle on/off:**
- Go to Settings (Cmd+,)
- Check/uncheck "Enable Auto-suggestions"

### 3. Multiple Tabs (Cmd+T)

Run multiple terminal sessions simultaneously.

**How to use:**
- `Cmd+T` - Open a new tab
- Click tab buttons to switch between tabs
- `Cmd+W` - Close current tab
- Each tab has its own independent shell session

**Use cases:**
- Monitor logs in one tab while working in another
- Run a development server in one tab, git commands in another
- Keep different project directories in separate tabs

### 4. AI Command Generation (Cmd+K)

Generate terminal commands from natural language descriptions.

**Setup (choose one):**

**Option A: Ollama (Free, Local, Recommended)**
```bash
# Install Ollama
brew install ollama

# Pull a model
ollama pull llama3.2:latest

# Ollama runs automatically in the background
```

Then in Enhanced Terminal:
1. Press `Cmd+,` for Settings
2. Select "Ollama" as AI Provider
3. Verify URL: `http://localhost:11434`
4. Set model: `llama3.2:latest`

**Option B: OpenAI (Requires API Key)**
1. Get API key from https://platform.openai.com/api-keys
2. Press `Cmd+,` for Settings
3. Select "OpenAI" as AI Provider
4. Enter your API key

**How to use:**
1. Press `Cmd+K`
2. Describe what you want to do in plain English
3. Click "Generate" or press Enter
4. Review the generated command
5. Click "Use Command" to insert it
6. Press Enter to execute

**Examples:**
- "find all PDF files larger than 10MB"
  → `find . -type f -name "*.pdf" -size +10M`

- "show me the 10 largest files in this directory"
  → `du -ah . | sort -rh | head -10`

- "kill all processes using port 8080"
  → `lsof -ti:8080 | xargs kill -9`

- "compress all log files older than 7 days"
  → `find . -name "*.log" -mtime +7 -exec gzip {} \;`

### 5. Command Snippets (Cmd+P)

Quick access to commonly used commands.

**How to use:**
1. Press `Cmd+P`
2. Browse or search for a snippet
3. Double-click or press Enter to use it

**Built-in categories:**
- **Files**: List files, find large files, disk usage
- **Git**: Status, log, commit, branch operations
- **Docker**: Container and image management
- **Network**: Port management, network connections
- **System**: Process management, system information

**Add your own snippets:**
1. Press `Cmd+P`
2. Click "Add New"
3. Enter name, command, category, and description
4. Your snippet is saved permanently

**Example custom snippets:**
- Name: "Deploy to production"
  Command: `git push origin main && ssh prod 'cd /app && ./deploy.sh'`
  Category: "Deployment"

- Name: "Backup database"
  Command: `pg_dump mydb > backup_$(date +%Y%m%d).sql`
  Category: "Database"

### 6. Themes

Choose from 4 beautiful themes:

**Dracula (Default)**
- Modern dark purple background
- High contrast, easy on the eyes
- Popular among developers

**Solarized Dark**
- Scientifically designed color scheme
- Low contrast, reduces eye strain
- Perfect for long coding sessions

**Nord**
- Arctic-inspired color palette
- Cool, calming colors
- Great for focus

**Classic**
- Retro green-on-black terminal
- Nostalgic hacker aesthetic
- High contrast

**Change theme:**
1. Press `Cmd+,` for Settings
2. Select theme from dropdown
3. Changes apply immediately to all tabs

### 7. Font Size Adjustment

**Keyboard shortcuts:**
- `Cmd+Plus` - Increase font size
- `Cmd+Minus` - Decrease font size
- `Cmd+0` - Reset to default (14pt)

**Or in Settings:**
1. Press `Cmd+,`
2. Enter font size (8-72)
3. Changes apply to all tabs

## ⌨️ Complete Keyboard Shortcuts

### Tabs & Navigation
| Shortcut | Action |
|----------|--------|
| `Cmd+T` | New tab |
| `Cmd+W` | Close current tab |
| Click tabs | Switch between tabs |

### Search & Tools
| Shortcut | Action |
|----------|--------|
| `Cmd+R` | Search command history |
| `Cmd+K` | AI Command Generator |
| `Cmd+P` | Command Snippets |
| `Tab` | Accept auto-suggestion |

### View
| Shortcut | Action |
|----------|--------|
| `Cmd+Plus` | Increase font size |
| `Cmd+Minus` | Decrease font size |
| `Cmd+0` | Reset font size |
| `Cmd+F` | Toggle fullscreen |

### Edit
| Shortcut | Action |
|----------|--------|
| `Cmd+C` | Copy selected text |
| `Cmd+V` | Paste |
| `Cmd+A` | Select all |

### Settings & Help
| Shortcut | Action |
|----------|--------|
| `Cmd+,` | Open Settings |
| `Cmd+Q` | Quit application |
| Type `help` | Show help in terminal |

## 💡 Pro Tips

### 1. Combine Features
- Use `Cmd+R` to find a complex command you used before
- Modify it slightly for your current need
- It gets added to history for next time

### 2. Build Your Snippet Library
- Whenever you create a complex command, save it as a snippet
- Add good descriptions and tags for easy searching
- Share snippets with your team

### 3. Use AI for Learning
- Generate commands with AI
- Study the generated command to learn new techniques
- Modify and experiment with the suggestions

### 4. Organize with Tabs
- Keep one tab for each project
- Use descriptive tab names (shown in tab bar)
- Switch quickly between contexts

### 5. Customize Your Experience
- Adjust font size for your display
- Choose a theme that matches your workflow
- Enable/disable auto-suggestions based on preference

## 🔧 Troubleshooting

### AI Not Working

**Ollama:**
- Check if Ollama is running: `ollama list`
- Verify the model is downloaded: `ollama pull llama3.2:latest`
- Check the URL in Settings: should be `http://localhost:11434`

**OpenAI:**
- Verify your API key is correct
- Check you have credits in your OpenAI account
- Test the key at https://platform.openai.com/playground

### Auto-suggestions Not Appearing
- Make sure they're enabled in Settings (Cmd+,)
- You need to have command history first
- Suggestions only appear for commands you've used before

### History Search Empty
- History builds up as you use the terminal
- Try running some commands first
- History persists between sessions

### Tab Not Responding
- Each tab runs an independent shell
- If a command hangs, close the tab (Cmd+W)
- Open a new tab (Cmd+T) to continue

### Window Not Showing
- Try `Cmd+Tab` to switch to the app
- Check if it's in fullscreen mode
- Quit and restart the application

## 🎓 Learning Resources

### Getting Started with Terminal
If you're new to terminal commands:
1. Type `help` in the terminal for built-in help
2. Use AI (Cmd+K) to learn commands
3. Browse snippets (Cmd+P) to see examples

### Common Commands to Try
```bash
# Navigation
ls          # List files
cd folder   # Change directory
pwd         # Print working directory

# File operations
cat file.txt    # View file contents
cp src dest     # Copy file
mv old new      # Move/rename file
rm file         # Delete file

# System info
date        # Show date/time
whoami      # Show current user
df -h       # Disk space
top         # Process monitor (press q to quit)

# Git basics
git status      # Check repository status
git log         # View commit history
git diff        # See changes
```

## 🚀 Advanced Usage

### Custom Shell Configuration
The terminal uses your existing shell configuration:
- `.zshrc` for zsh (default on macOS)
- `.bashrc` for bash
- All your aliases and functions work

### Environment Variables
All your environment variables are available:
```bash
echo $PATH
echo $HOME
echo $USER
```

### Piping and Redirection
Full support for Unix pipes and redirection:
```bash
ls -la | grep ".txt"
cat file.txt | wc -l
echo "hello" > output.txt
```

### Background Jobs
Run commands in the background:
```bash
long_running_command &
```

Note: The terminal handles job control properly, so you won't see "fg: no job control" errors.

## 📊 Performance Tips

### For Large Output
- Use `less` or `more` for large files
- Pipe to `head` or `tail` to limit output
- Clear screen regularly with `clear` or Cmd+K

### For Many Tabs
- Close unused tabs to free memory
- Each tab runs a separate shell process
- Recommended: Keep 5-10 tabs maximum

### History Management
- History is limited to 1000 commands
- Clear history if needed: Tools → Clear History
- Old commands are automatically removed

## 🎨 Customization Ideas

### Create Workflow Snippets
Save entire workflows as snippets:
```bash
# Development workflow
git pull && npm install && npm run dev

# Deployment workflow
npm run build && npm test && git push

# Backup workflow
tar -czf backup.tar.gz project/ && scp backup.tar.gz server:~/
```

### Use AI for Complex Tasks
Let AI help with:
- Complex find commands
- Advanced git operations
- System administration tasks
- Data processing with awk/sed

### Theme Switching
Switch themes based on:
- Time of day (dark themes at night)
- Task (Classic for focused work)
- Mood (Nord for calm, Dracula for energy)

---

**Need more help?** Type `help` in the terminal or check the README.md file.

**Enjoy your enhanced terminal experience! 🚀**