sugcommand 0.3.0

Intelligent terminal command suggestion tool with real-time shell integration, customizable key bindings, and smart command history analysis

SugCommand - Intelligent Terminal Command Suggestion Tool

SugCommand is an intelligent Python library that provides terminal command suggestions based on:

• Available system commands
• Command history analysis from different shells
• Usage patterns and context
• Simple machine learning algorithms
• 🚀 NEW: REAL-TIME AUTO-SUGGESTIONS - Automatic suggestions while typing!

✨ Key Features

🎯 NEW: Real-time Auto-Suggestions

• 💡 Automatic display: Suggestions appear as you type - no Tab needed!
• ⚡ Ultra-fast: Sub-3ms response time
• 🎨 Beautiful display: Elegant suggestions below your cursor
• 🔧 Zero config: Works out of the box
• 🖥️ Multi-shell: Bash, Zsh, Fish support

🔍 Smart Command Detection

• Scans all available commands from PATH and system directories
• Supports fuzzy and exact matching
• Intelligent caching for speed

📚 History Analysis

• Supports bash, zsh, fish shell history
• Learns patterns from previous usage
• Context-aware suggestions based on command sequences

🎯 Customizable Key Bindings

• Multiple binding options (Ctrl+Space, Ctrl+@, Ctrl+], etc.)
• Shell-specific bindings for bash/zsh/fish
• Real-time trigger for instant suggestions
• Fallback completion when needed

🚀 Real-time Shell Integration

• Automatic suggestions while typing (no need to run sugcommand separately)
• Integration with bash/zsh/fish tab completion
• Background daemon for fast response (<50ms)
• Custom key bindings for instant suggestions

⚡ High Performance

• Parallel directory scanning
• Intelligent caching with TTL
• Response time < 100ms
• Daemon architecture for real-time response

🎨 Beautiful Interface

• Customizable colors (supports dark/light themes)
• Shows confidence scores and suggestion sources
• Compact mode for small terminals

⚙️ Flexible Configuration

• Enable/disable individual features
• Customize number of suggestions
• Exclude/include commands
• Export/import configuration

🚀 Installation

From PyPI (Recommended)

pip install sugcommand

From Source

git clone https://github.com/yourusername/sugcommand.git
cd sugcommand
pip install -e .

System Requirements

• Python 3.8+
• Linux/macOS/WSL
• Terminal with ANSI color support

🎯 Setup Auto-Completion (IMPORTANT!)

This is the main feature! To get automatic suggestions while typing:

Step 1: Install shell integration

# Auto-detect shell and install
sugcommand integration install

# Or specify shell
sugcommand integration install --shell bash
sugcommand integration install --shell zsh
sugcommand integration install --shell fish

Step 2: Start daemon

# Start daemon in background
sugcommand daemon start --background

# Check daemon status
sugcommand daemon status

Step 3: Add to shell config

Bash: Add to ~/.bashrc:

source ~/.config/sugcommand/bash_completion.sh

Zsh: Add to ~/.zshrc:

source ~/.config/sugcommand/zsh_completion.zsh

Fish: Fish loads automatically, or add to ~/.config/fish/config.fish:

source ~/.config/sugcommand/fish_completion.fish

Step 4: Restart shell and test

# Restart shell
exec $SHELL

# Test auto-completion
git c<TAB>      # Will suggest: commit, clone, checkout...
apt u<TAB>      # Will suggest: update, upgrade...
docker r<TAB>   # Will suggest: run, rm, restart...

📖 Usage

Basic Usage (CLI)

# Get suggestions for a command
sugcommand suggest "apt"

# Get suggestions with interactive mode
sugcommand suggest

# Show with confidence scores
sugcommand suggest "git" --show-confidence

# Compact mode
sugcommand suggest "docker" --compact

# Limit number of suggestions
sugcommand suggest "npm" --limit 5

Daemon Management

# Start/stop daemon
sugcommand daemon start --background
sugcommand daemon stop
sugcommand daemon status

# Check integration status
sugcommand integration status

Configuration Management

# Enable/disable suggestions
sugcommand enable
sugcommand disable
sugcommand toggle

# View statistics
sugcommand stats
sugcommand stats --engine
sugcommand stats --performance

# Configuration
sugcommand config set max_suggestions 15
sugcommand config get enabled
sugcommand config reset

# Export/Import configuration
sugcommand config export my-config.json
sugcommand config import my-config.json

Using in Python

from sugcommand import SuggestionEngine, ConfigManager
from sugcommand.integrations.realtime_daemon import DaemonClient

# Use daemon (fastest)
client = DaemonClient()
suggestions = client.get_suggestions("git c")

# Or use engine directly
config = ConfigManager()
engine = SuggestionEngine(config)
suggestions = engine.get_suggestions("git c")

for suggestion in suggestions:
    print(f"{suggestion['command']} (confidence: {suggestion['confidence']:.2f})")

🔧 Key Bindings

After installing shell integration, you can use:

• Tab: Enhanced completion with suggestions
• Ctrl+Space: Show suggestions for current command (bash)
• Ctrl+X (fish): Show suggestions for current command
• Ctrl+X Ctrl+S (zsh): Show suggestions for current command

Custom Key Bindings

You can customize key bindings in your shell configuration:

Bash:

# In ~/.bashrc
bind -x '"\\C- ": _sugcommand_realtime_display'  # Ctrl+Space
# Or use other keys:
# bind -x '"\\C-@": _sugcommand_realtime_display'  # Ctrl+@
# bind -x '"\\C-]": _sugcommand_realtime_display'  # Ctrl+]

Zsh:

# In ~/.zshrc
bindkey '^ ' _sugcommand_widget    # Ctrl+Space
# Or use other keys:
# bindkey '^]' _sugcommand_widget    # Ctrl+]

Fish:

# In ~/.config/fish/config.fish
bind \e[32~ __sugcommand_show_suggestions  # F2
# Or use other keys:
# bind \e[33~ __sugcommand_show_suggestions  # F3

🔧 Advanced Configuration

Configuration File

SugCommand stores configuration at ~/.config/sugcommand/config.json:

{
  "enabled": true,
  "max_suggestions": 10,
  "show_confidence": false,
  "color_enabled": true,
  "history_analysis_enabled": true,
  "command_scan_enabled": true,
  "fuzzy_search_enabled": true,
  "min_confidence_threshold": 0.1,
  "cache_duration": 3600,
  "daemon_enabled": true,
  "shell_integration_enabled": true,
  "custom_directories": [
    "/opt/custom/bin"
  ],
  "excluded_commands": [
    "history",
    "clear"
  ]
}

Custom Scan Directories

# Add custom directories
sugcommand config set custom_directories '["/opt/myapp/bin", "~/scripts"]'

# Exclude commands
sugcommand config set excluded_commands '["passwd", "sudo -s"]'

Color Schemes

# Choose color scheme
sugcommand config set color_scheme "dark"    # dark, light, minimal
sugcommand config set color_enabled false   # Disable colors

🏗️ Architecture

sugcommand/
├── core/
│   ├── command_scanner.py     # System command scanning
│   ├── history_analyzer.py    # History analysis
│   ├── suggestion_engine.py   # Main engine
│   └── config_manager.py      # Configuration management
├── integrations/             # ✨ NEW: Shell Integration
│   ├── realtime_daemon.py     # Daemon for real-time suggestions
│   ├── bash_integration.py    # Bash completion integration
│   ├── zsh_integration.py     # Zsh completion integration
│   └── fish_integration.py    # Fish completion integration
├── utils/
│   ├── display.py            # Display formatting
│   └── performance.py        # Performance monitoring
└── cli.py                    # Command line interface

Real-time Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Shell Input   │───▶│  Completion      │───▶│   SugCommand    │
│   (git c<TAB>)  │    │  Script          │    │   Daemon        │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │                        │
                                ▼                        ▼
                       ┌──────────────────┐    ┌─────────────────┐
                       │  Unix Socket     │◀───│  Suggestion     │
                       │  Communication   │    │  Engine         │
                       └──────────────────┘    └─────────────────┘
                                │                        │
                                ▼                        ▼
                       ┌──────────────────┐    ┌─────────────────┐
                       │  Fast Response   │    │  Cache &        │
                       │  (<50ms)         │    │  History        │
                       └──────────────────┘    └─────────────────┘

📊 Algorithm

Scoring Algorithm

def calculate_confidence(suggestion):
    score = 0.0
    
    # Exact match bonus
    if exact_match:
        score += 1.0
    
    # Prefix match
    elif prefix_match:
        score += 0.8
    
    # Frequency bonus from history
    score += frequency_weight * (usage_count / total_commands)
    
    # Recency bonus
    score += recency_weight * (1.0 / days_since_last_use)
    
    # Context bonus (sequence patterns)
    score += context_weight * sequence_probability
    
    return min(score, 1.0)

Real-time Performance

Component               Response Time
─────────────────────────────────────
Command Scanner:        ~20ms
History Analysis:       ~15ms  
Suggestion Engine:      ~10ms
Daemon Communication:   ~5ms
─────────────────────────────────────
Total (with daemon):    ~50ms
Total (without daemon): ~100ms

🔧 Development

Setup development environment

git clone https://github.com/yourusername/sugcommand.git
cd sugcommand

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or venv\Scripts\activate  # Windows

# Install dependencies
pip install -e ".[dev,daemon]"

# Run tests
pytest

# Code formatting
black src/
isort src/

# Type checking
mypy src/

Test shell integration

# Test daemon
python -c "from sugcommand.integrations.realtime_daemon import RealtimeDaemon; d = RealtimeDaemon(); d.start()"

# Test completions
python -c "from sugcommand.integrations.bash_integration import BashIntegration; b = BashIntegration(); b.test_completion('git c')"

# Test client
python -c "from sugcommand.integrations.realtime_daemon import DaemonClient; c = DaemonClient(); print(c.get_suggestions('git c'))"

Run tests

# All tests
pytest

# With coverage
pytest --cov=sugcommand --cov-report=html

# Test specific module
pytest tests/test_daemon.py -v

Build package

# Build wheel
python -m build

# Upload to PyPI
twine upload dist/*

📈 Performance

Benchmarks

Real-time Mode (with daemon):
──────────────────────────────
Command Scanning: ~20ms (avg)
History Analysis: ~15ms (avg)
Suggestion Generation: ~10ms (avg)
Daemon Communication: ~5ms (avg)
Total Response Time: ~50ms (95th percentile)

Direct Mode (without daemon):
─────────────────────────────
Command Scanning: ~50ms (avg)
History Analysis: ~30ms (avg)  
Suggestion Generation: ~20ms (avg)
Total Response Time: ~100ms (95th percentile)

Memory Usage: ~15MB (daemon) + ~8MB (per client)
Cache Hit Rate: >95% (after warmup)

Optimization tips

1. Use daemon mode: Daemon keeps cache warm and responds quickly
2. Enable shell integration: Smoothest automatic completion
3. Limit scan directories: Remove unnecessary directories
4. Exclude commands: Exclude unnecessary commands
5. Warm up cache: Run sugcommand refresh after installation

🎯 Use Cases

1. Developer Workflow

git s<TAB>     → status, stash, show
npm i<TAB>     → install, init, info
docker r<TAB>  → run, rm, restart

2. System Administration

systemctl s<TAB>    → start, stop, status
apt u<TAB>          → update, upgrade
sudo service <TAB>  → apache2, nginx, mysql

3. Python Development

pip i<TAB>      → install, info, list
python -m <TAB> → pip, venv, pytest
pytest -<TAB>   → -v, --cov, --help

🚨 Troubleshooting

Daemon won't start

# Check port conflict
sugcommand daemon status

# Check logs
tail -f ~/.config/sugcommand/daemon.log

# Restart daemon
sugcommand daemon stop
sugcommand daemon start --background

Tab completion not working

# Check integration
sugcommand integration status

# Reinstall integration
sugcommand integration install --shell bash

# Source shell config
source ~/.bashrc  # or ~/.zshrc

Slow performance

# Warm up cache
sugcommand refresh

# Check performance
sugcommand stats --performance

# Reduce scan directories
sugcommand config set custom_directories '[]'

📝 Changelog

v0.2.0 (2024-01-XX)

• 🎯 Customizable Key Bindings: Multiple binding options and triggers
• 🔄 Enhanced Shell Integration: Improved real-time suggestions
• ⚡ Performance Improvements: Faster response times
• 🔧 Better Error Handling: More reliable suggestion display

v0.1.0 (2024-01-XX)

• ✨ Shell Integration: Real-time auto-completion for bash/zsh/fish
• ⚡ Daemon Architecture: Background daemon for fast response
• 🔍 Command scanning and indexing
• 📚 Multi-shell history analysis
• 🎨 Beautiful CLI interface with colors
• ⚙️ Comprehensive configuration system
• 📊 Performance monitoring
• 🚀 Tab completion enhancement
• 🔧 Key bindings for real-time suggestions

📄 License

This project is licensed under the MIT License. See LICENSE for details.

⭐ If you find this useful, please star the repository! ⭐

🎯 Quick Start Summary

# 1. Install
pip install sugcommand

# 2. Setup auto-completion
sugcommand integration install
sugcommand daemon start --background

# 3. Add to shell config
echo 'source ~/.config/sugcommand/bash_completion.sh' >> ~/.bashrc

# 4. Restart shell
exec $SHELL

# 5. Enjoy auto-completion!
git c<TAB>  # 🎉 Suggestions appear!