linux-clipboard-manager 1.1.0

A powerful clipboard manager with history, search, and smart categorization

📋 Smart Clipboard Manager

A powerful clipboard manager with history, search, and smart categorization features.

🚀 Quick Install • 📖 Features • 🎯 Usage • ⚙️ Configuration

---

✨ Features

🎯 Core Features

• 📋 Clipboard History: Automatically saves your last 1000 clipboard entries
• 🔍 Smart Search: Full-text search across all clipboard history
• 🏷️ Auto-Categorization: Automatically detects URLs, emails, code, file paths, and more
• ⭐ Favorites: Pin frequently used clips for quick access
• 🔒 Privacy Protection: Automatically excludes sensitive content from password managers
• 🎯 Deduplication: Doesn't store identical content twice
• ⌨️ Global Hotkey: Quick access with Ctrl+Alt+V
• 🔄 Auto-Refresh: Shows newly copied items immediately

🎨 User Interface

• Modern UI: Clean, intuitive interface with dark/light theme support
• Click-to-Copy: Single click on any item to copy it to clipboard
• Real-time Updates: See new clipboard items appear instantly
• Smart Filtering: Filter by content type (URLs, Code, Favorites, etc.)
• Preview Panel: Full content preview with syntax highlighting for code

🛡️ Security & Privacy

• Local Storage: All data stored locally in SQLite database
• No Cloud Sync: By default, no data leaves your machine
• App Exclusion: Automatically excludes clipboard content from password managers
• Sensitive Content Detection: Detects and optionally excludes passwords, credit cards, etc.

---

🚀 Quick Install

Option 1: Install via pipx (Recommended)

# Install pipx if you don't have it
sudo apt install pipx
pipx ensurepath

# Install from PyPI
pipx install linux-clipboard-manager

Option 2: Install from source

# Install from GitHub
pipx install git+https://github.com/krakujs/linux-clipboard-manager.git

Option 3: One-Click System Installation

# Download and run the installation script (installs system dependencies + app)
curl -fsSL https://raw.githubusercontent.com/krakujs/linux-clipboard-manager/master/install-system.sh | bash

---

🎯 Usage

After Installation

1. Start the Application: Run smart-clipboard in a terminal to start the background service
2. Open the UI: Press Ctrl+Alt+V to toggle the clipboard manager window (while service is running)
3. Or Open GUI Directly: Run smart-clipboard-gui to open just the UI
4. Copy Items: Click on any item to copy it to your clipboard
5. Search: Type in the search box to filter clipboard history
6. Filter by Type: Click buttons to filter by content type (All, URLs, Code, Favorites)

Keyboard Shortcuts

Shortcut	Action
Ctrl+Alt+V	Toggle clipboard manager window
Enter	Paste selected clip
Escape	Close window
Double-click	Paste selected clip

Command Line Usage

# Start background service (monitors clipboard + hotkey)
smart-clipboard

# Open GUI only (no background monitoring)
smart-clipboard-gui

# Start with UI visible
smart-clipboard --show-ui

---

⚙️ Configuration

The configuration file is located at: ~/.smart-clipboard/config.json

Default Configuration

{
  "max_history": 1000,
  "monitor_interval": 0.5,
  "hotkey": "<ctrl>+<alt>+v",
  "database_path": "clipboard.db",
  "max_content_size": 1048576,
  "enable_encryption": false,
  "excluded_apps": ["KeePass", "1Password", "LastPass"],
  "categories": {
    "url": true,
    "email": true,
    "code": true,
    "image": true
  },
  "ui": {
    "max_preview_length": 100,
    "window_width": 600,
    "window_height": 400,
    "theme": "light"
  }
}

Customizing the Hotkey

Edit the hotkey field in config.json. Examples:

• <ctrl>+<alt>+v (default)
• <ctrl>+<shift>+c
• <cmd>+<shift>+v (macOS)

---

📦 System Requirements

Linux

• Python 3.7 or higher
• pip (Python package manager)
• System dependencies:

  sudo apt install python3 python3-pip python3-venv python3-full sqlite3 xdotool
  

Other Platforms

• Windows: Additional pywin32 and psutil packages required
• macOS: No additional dependencies needed (uses built-in AppleScript)

---

🔧 Development

Setting up Development Environment

# Clone the repository
git clone https://github.com/your-username/smart-clipboard-manager.git
cd smart-clipboard-manager

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run the application
python main.py

Running Tests

# Install test dependencies
pip install -r requirements.txt

# Run tests
pytest tests/

# Run with coverage
pytest --cov=src tests/

Project Structure

smart-clipboard-manager/
├── src/
│   ├── __init__.py
│   ├── clipboard_monitor.py    # Background clipboard monitoring
│   ├── storage.py               # SQLite storage engine
│   ├── ui.py                    # Tkinter GUI interface
│   ├── hotkey_handler.py        # Global hotkey management
│   ├── content_analyzer.py      # Content categorization
│   └── config.py                # Configuration management
├── tests/                       # Test suite
├── requirements.txt             # Python dependencies
├── setup.py                     # Package configuration
├── install-system.sh           # System installation script
├── main.py                      # Application entry point
└── README.md                    # This file

---

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

How to Contribute

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• pyperclip for cross-platform clipboard access
• pynput for global hotkey handling
• Tkinter for the GUI framework

---

📞 Support

• 🐛 Bug Reports: Open an issue
• 💡 Feature Requests: Open an issue
• 💬 Discussions: GitHub Discussions

---

🔄 Changelog

v1.0.1 (2024-11-05)

• 🔧 Changed hotkey from Ctrl+Shift+V to Ctrl+Alt+V to avoid conflicts
• 📚 Updated documentation with new hotkey information
• 🐛 Fixed hotkey collision issues with other applications

v1.0.0 (2024-11-05)

• ✨ Initial release
• 📋 Clipboard history with 1000 item limit
• 🔍 Full-text search functionality
• 🏷️ Smart content categorization
• ⭐ Favorites system
• ⌨️ Global hotkey support
• 🔄 Auto-refresh functionality
• 🖥️ Modern UI with click-to-copy
• 🔧 System service integration
• 📦 Easy installation scripts

---

Made with ❤️ for productivity enthusiasts

⭐ Star this repo • 🐛 Report issues • 💬 Start a discussion