📋 Clipboard Monitor

Aplicação desktop inteligente para monitoramento e gerenciamento de histórico do clipboard no Linux

Características • Instalação • Uso • Documentação • Contribuindo

---

🚀 Sobre o Projeto

Clipboard Monitor é uma solução completa e elegante para gerenciar seu histórico de clipboard no Linux. Desenvolvida com PyQt5, oferece uma interface moderna e discreta através de um ícone na bandeja do sistema, enquanto monitora e indexa automaticamente tudo que você copia.

💡 Por que Clipboard Monitor?

• 🔄 Nunca perca nada: Todo conteúdo copiado é automaticamente salvo e indexado
• 🔍 Busca instantânea: Engine de busca full-text com SQLite FTS5
• 💾 Organização inteligente: Estrutura de diretórios por data (YYYY/MM/DD)
• ⚡ Performance: Monitoramento leve e não-intrusivo
• 🎨 Interface elegante: Ícone na bandeja com menu contextual completo
• 🔐 Privacidade: Tudo armazenado localmente, sem cloud

---

✨ Características

Core Features

• ✅ Monitoramento Automático - Captura todo texto copiado automaticamente
• ✅ Deduplicação Inteligente - SHA256 hash previne salvamento de duplicatas
• ✅ Busca Full-Text - SQLite FTS5 para buscas instantâneas
• ✅ Filtros Avançados - Por data, tamanho, conteúdo
• ✅ Preview em Tempo Real - Visualize conteúdo antes de usar
• ✅ Notificações Desktop - Feedback visual ao salvar
• ✅ Multi-Platform Clipboard - Suporte X11 (xclip) e Wayland (wl-paste)
• ✅ Configurações Completas - Interface gráfica para todas as opções

Interface

🎯 System Tray Status em tempo real Menu contextual completo Indicadores visuais (ativo/pausado/erro) Contagem de itens do dia	🔍 Janela de Busca Busca em tempo real (debounced) Filtros por data e tamanho Preview de conteúdo completo Ações: Copiar, Abrir, Deletar
⚙️ Configurações 4 tabs organizadas Validação de inputs Live preview de alterações Persistência em JSON	⌨️ Atalhos Ctrl+F - Focar busca Enter - Copiar item Del - Deletar item Esc - Fechar janela

---

🛠️ Tecnologias

Categoria	Tecnologia
Linguagem	Python 3.12+
GUI Framework	PyQt5 5.15+
Database	SQLite 3 com FTS5
Clipboard	xclip (X11) / wl-paste (Wayland)
Arquitetura	MVC + Threading (QThread)

Arquitetura

clipboard-monitor/
├── core/           # Lógica de negócios
│   ├── config      # Gerenciamento de configurações
│   ├── clipboard   # Abstração de clipboard tools
│   ├── storage     # Persistência de arquivos
│   └── monitor     # Thread de monitoramento
├── ui/             # Interface gráfica
│   ├── tray        # System tray icon
│   ├── search      # Janela de busca
│   └── settings    # Diálogo de configurações
└── search/         # Sistema de busca
    ├── indexer     # Indexação SQLite FTS5
    └── query       # Query engine

---

📦 Instalação

Pré-requisitos

# Ubuntu/Debian
sudo apt install python3 python3-pyqt5 xclip

# Arch Linux
sudo pacman -S python python-pyqt5 xclip

# Para Wayland (opcional)
sudo apt install wl-clipboard

Instalação Rápida

# Clone o repositório
git clone https://github.com/johnnyvaz/clipboard-monitor.git
cd clipboard-monitor

# Execute o instalador
./app/install.sh

# Inicie a aplicação
python3 app/main.py

Ou via Git

git clone https://github.com/johnnyvaz/clipboard-monitor.git
cd clipboard-monitor/app
chmod +x main.py install.sh
./install.sh

---

🎯 Uso

Iniciar Aplicação

# Método 1: Direto
cd clipboard-monitor/app
python3 main.py

# Método 2: Autostart (após instalação)
# Faça logout/login - o app inicia automaticamente

Interface da Bandeja

Após iniciar, procure pelo ícone na bandeja do sistema:

● Monitorando (status)
────────────────────
▶ Iniciar / ⏸ Pausar
────────────────────
🔍 Buscar Clipboard...
📁 Abrir Pasta
────────────────────
⚙ Configurações
ℹ Sobre
────────────────────
❌ Sair

Busca e Filtros

1. Click no ícone → "Buscar Clipboard"
2. Digite sua busca (full-text search)
3. Aplique filtros:
   • Data: De/Até ou atalhos (Hoje, 7 dias)
   • Tamanho: Mínimo/Máximo em KB
   • Case sensitive: Opcional
4. Double-click em resultado para copiar
5. Preview: Veja conteúdo completo antes de copiar

Configurações

Acesse via menu → "Configurações":

Tab 1 - Geral

• ☑ Notificações ao salvar
• ☑ Iniciar com o sistema
• 📁 Local do arquivo

Tab 2 - Monitoramento

• ⏱️ Intervalo de checagem (0.1-5.0s)
• 📏 Tamanho máximo (KB)
• 🔢 Filtro binário (bytes nulos)

Tab 3 - Armazenamento

• 🗑️ Limpeza automática
• 📅 Dias para manter
• 💾 Tamanho máximo do arquivo

Tab 4 - Avançado

• 🛠️ Ferramenta clipboard (auto/xclip/wl-paste)
• 🐛 Debug logging

---

📂 Estrutura de Arquivos

Onde os arquivos são salvos:

~/Documentos/clipboard_md/
└── 2026/
    └── 01/
        └── 07/
            ├── 14-30-45.md
            ├── 14-31-12.md
            └── 14-32-08.md

Formato dos arquivos:

---
captured_at: "2026-01-07T14:30:45-03:00"
bytes: 1234
---

[Conteúdo do clipboard aqui]

Outros arquivos:

~/.config/clipboard-monitor/config.json    # Configurações
~/.cache/clipboard-monitor/index.db        # Índice de busca
~/.cache/clipboard-monitor/app.lock        # Process lock

---

🧪 Compatibilidade

Testado em:

OS	Desktop	Python	PyQt5	Status
Ubuntu 24.04	GNOME	3.12.3	5.15.10	✅
Ubuntu 22.04	GNOME	3.10+	5.15+	✅
Debian 12	GNOME/KDE	3.11+	5.15+	✅
Arch Linux	GNOME/KDE	3.12+	5.15+	✅

Display Servers:

• ✅ X11 (via xclip)
• ✅ Wayland (via wl-paste)
• ✅ Auto-detecção inteligente

---

🎨 Screenshots

📸 Clique para ver mais screenshots

Interface Principal

Janela de Busca

Configurações

---

🏗️ Desenvolvimento

Setup do Ambiente

# Clone o repositório
git clone https://github.com/johnnyvaz/clipboard-monitor.git
cd clipboard-monitor

# Instale dependências (já incluídas no sistema)
python3 -c "from PyQt5 import QtCore; print('PyQt5 OK')"

# Execute em modo de desenvolvimento
cd app
python3 main.py

Estrutura do Código

# Exemplo: Criar instância do monitor
from clipboard_monitor.core.config import Config
from clipboard_monitor.core.storage import StorageManager
from clipboard_monitor.core.monitor import ClipboardMonitor

config = Config()
storage = StorageManager()
monitor = ClipboardMonitor(config, storage)
monitor.start()

Testes

# Teste de imports
python3 -c "
from clipboard_monitor.core import *
from clipboard_monitor.ui import *
from clipboard_monitor.search import *
print('All imports OK!')
"

# Teste de instâncias
python3 -c "
from clipboard_monitor.core.config import Config
config = Config()
print(f'Config OK: {config.get(\"monitoring.interval\")}')"

---

🤝 Contribuindo

Contribuições são sempre bem-vindas! Veja CONTRIBUTING.md para detalhes.

Como Contribuir

1. Fork o projeto
2. Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
3. Commit suas mudanças (git commit -m 'Add: Amazing new feature')
4. Push para a branch (git push origin feature/AmazingFeature)
5. Abra um Pull Request

Roadmap

• Suporte a imagens do clipboard
• Sync cloud (opcional)
• Categorização automática (URLs, código, texto)
• Clipboard history quick access (Ctrl+Shift+V)
• Favorites/pinned items
• Export para vários formatos
• GNOME Shell extension
• Themes customizáveis

---

📝 Changelog

v1.0.0 (2026-01-07)

🎉 Initial Release

• ✨ Monitoramento automático de clipboard
• 🔍 Busca full-text com SQLite FTS5
• 🎨 Interface gráfica completa (tray, search, settings)
• 💾 Armazenamento organizado por data
• ⚙️ Sistema de configurações completo
• 🔔 Notificações desktop
• 🔐 Deduplicação SHA256
• 📱 Suporte X11 e Wayland

---

📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

---

👨‍💻 Autor

Johnny Vaz

Full Stack Developer | Technology Entrepreneur | Career Mentor

💼 Experiência

• 10+ anos em sistemas ERP
• 8+ anos como analista e desenvolvedor de sistemas
• Especialista em Full Stack (Java, JavaScript, TypeScript, Python, PHP)
• Founder de múltiplos produtos SaaS
• Mentor de carreira em tecnologia

🛠️ Tech Stack

🚀 Featured Projects

• Cod2D Software - ERP/CRM/E-commerce para distribuidores
• Contrato Automático - Automação de contratos com IA
• ValeCar - Proteção veicular digital 24/7
• Desktop Cloud - Desktops Windows na nuvem
• LealFidelizações - Sistema de cashback via WhatsApp
• Estude Online - Plataforma de cursos profissionalizantes

---

🙏 Agradecimentos

• Comunidade PyQt5 pelos excelentes recursos
• Desenvolvedores do xclip e wl-clipboard
• Todos que testaram e deram feedback

---

⭐ Mostre seu apoio

Se este projeto foi útil para você, considere dar uma ⭐️!

---

⬆ Voltar ao topo

Feito com ❤️ e ☕ por Johnny Vaz