📋 ClipStack

The ultimate cross-platform clipboard manager for developers 🚀

ClipStack is a powerful, terminal-first clipboard manager that helps developers never lose their copied content again. Built with Python and designed for productivity, it provides instant access to your clipboard history with lightning-fast search and seamless cross-platform support.

✨ Features

• 🔄 Real-time clipboard tracking - Never lose copied content
• 🚀 Lightning-fast fuzzy search - Find anything in your history instantly
• 💾 Smart storage - JSON-based storage with duplicate prevention
• 🎨 Beautiful terminal UI - Rich, colorful output with timestamps
• 🔧 Developer-friendly - Simple CLI with intuitive commands
• 🌍 Cross-platform - Works on macOS, Linux, and Windows
• 📱 TUI mode - Interactive terminal interface for power users
• 📤 Import/Export - Backup and restore your clipboard history
• 🧪 Fully tested - Comprehensive test coverage with pytest

🎯 Why ClipStack?

• Fast: Built with performance in mind using optimized search algorithms
• Reliable: Robust error handling and data persistence
• Extensible: Modular architecture for easy customization
• Beautiful: Rich terminal output that makes your terminal look professional
• Cross-platform: Works seamlessly across all major operating systems

🚀 Quick Start

Installation

# Install from PyPI (recommended)
pip install clipstack

# Or install from source
git clone https://github.com/yourusername/clipstack.git
cd clipstack
pip install -e .

Basic Usage

# Save current clipboard content
clipstack add

# View your clipboard history
clipstack list

# Search for specific content
clipstack search "python code"

# Restore the last copied item
clipstack pop

# Restore a specific item by index
clipstack restore 5

# Clear your history
clipstack clear

📖 Full Command Reference

Command	Description	Example
add	Save current clipboard content	clipstack add
list	Display clipboard history	clipstack list
peek	Show last copied item	clipstack peek
pop	Restore last item to clipboard	clipstack pop
restore <index>	Restore specific item	clipstack restore 3
search <query>	Fuzzy search history	clipstack search "api key"
clear	Clear entire history	clipstack clear
export <file>	Export to JSON/CSV	clipstack export backup.json
import <file>	Import from JSON/CSV	clipstack import backup.json
tui	Interactive terminal UI	clipstack tui

🎨 Screenshots

Main Interface

📋 ClipStack - Your Clipboard History

┌─ Index ── Timestamp ──────────────── Preview ──────────────────────────────┐
│   0    │ 2024-01-15 14:30:22 │ import requests; response = requests.get(url) │
│   1    │ 2024-01-15 14:25:15 │ https://api.github.com/users/username      │
│   2    │ 2024-01-15 14:20:08 │ git commit -m "feat: add new feature"      │
│   3    │ 2024-01-15 14:15:42 │ docker run -it ubuntu:latest               │
└─────────────────────────────────────────────────────────────────────────────┘

Search Results

🔍 Search Results for "python"

┌─ Index ── Timestamp ──────────────── Preview ──────────────────────────────┐
│   0    │ 2024-01-15 14:30:22 │ import requests; response = requests.get(url) │
│   5    │ 2024-01-15 13:45:10 │ def hello_world(): print("Hello, Python!")   │
└─────────────────────────────────────────────────────────────────────────────┘

🛠️ Configuration

ClipStack stores its configuration and history in:

• History: ~/.clipstack.json
• Config: ~/.clipstack/config.toml

Customization Options

# ~/.clipstack/config.toml
[storage]
max_history = 200
storage_type = "json"  # or "sqlite" (future)

[display]
max_preview_length = 80
show_timestamps = true
color_scheme = "auto"

[clipboard]
auto_track = true
track_interval = 1.0

🧪 Development

Setting up the development environment

# Clone the repository
git clone https://github.com/yourusername/clipstack.git
cd clipstack

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Install in development mode
pip install -e .

# Run tests
pytest

# Run linting
black .
flake8 .

Project Structure

clipstack/
├── clipstack/           # Main package
│   ├── __init__.py
│   ├── cli.py          # CLI interface
│   ├── clipboard.py    # Clipboard operations
│   ├── storage.py      # Data persistence
│   ├── search.py       # Search functionality
│   └── tui.py          # Terminal UI
├── tests/              # Test suite
├── docs/               # Documentation
├── requirements.txt     # Production dependencies
├── requirements-dev.txt # Development dependencies
├── setup.py            # Package configuration
├── pyproject.toml      # Modern Python packaging
└── README.md           # This file

🤝 Contributing

We love contributions! Here's how you can help:

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

Development Guidelines

• Follow PEP 8 style guidelines
• Write tests for new functionality
• Update documentation as needed
• Use conventional commit messages

Areas for Contribution

• 🚀 Performance improvements
• 🎨 UI/UX enhancements
• 🔧 Additional storage backends
• 📱 Mobile/desktop integrations
• 🌍 Internationalization
• 📊 Analytics and insights

📄 License

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

🙏 Acknowledgments

• Typer - Modern CLI framework
• Rich - Beautiful terminal output
• pyperclip - Cross-platform clipboard
• rapidfuzz - Fast fuzzy search
• Textual - Terminal UI framework

📊 Project Status

• ✅ Core functionality - Complete
• ✅ Cross-platform support - Complete
• ✅ Testing - Complete
• ✅ Documentation - Complete
• 🔄 Performance optimization - Ongoing
• 🔄 Additional features - In development

🌟 Star History

---

Made with ❤️ by the ClipStack community

If you find this project useful, please consider giving it a ⭐️ star on GitHub!