clipstack 0.1.0
A powerful, cross-platform clipboard manager for developers
License: MIT
Requires Python: >=3.10
Keywords: clipboard, manager, terminal, cli, productivity, developer-tools

# 📋 ClipStack

> **The ultimate cross-platform clipboard manager for developers** 🚀

[![PyPI version](https://badge.fury.io/py/clipstack.svg)](https://badge.fury.io/py/clipstack)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Tests](https://img.shields.io/badge/tests-pytest-blue.svg)](https://docs.pytest.org/)

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

```bash
# 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

```bash
# 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

```toml
# ~/.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

```bash
# 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](https://pep8.org/) 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](LICENSE) file for details.

## 🙏 Acknowledgments

- [Typer](https://typer.tiangolo.com/) - Modern CLI framework
- [Rich](https://rich.readthedocs.io/) - Beautiful terminal output
- [pyperclip](https://pypi.org/project/pyperclip/) - Cross-platform clipboard
- [rapidfuzz](https://github.com/maxbachmann/rapidfuzz) - Fast fuzzy search
- [Textual](https://textual.textualize.io/) - 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

[![Star History Chart](https://api.star-history.com/svg?repos=yourusername/clipstack&type=Date)](https://star-history.com/#yourusername/clipstack&Date)

---

**Made with ❤️ by the ClipStack community**

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