📎 clip-md

Copy what matters. Save it as Markdown in one click.

💬  Copied a useful AI response, then lost it among tabs and clipboard history? 📝  Tired of opening an editor, creating a file, choosing a folder, and naming it every time? 🧠  Want research notes, technical explanations, and useful snippets to stay organized without breaking focus?

✨ clip-md turns copied text into a local, smart-named Markdown archive.

AI responses · research notes · code explanations · any text worth keeping

Copy → M↓ appears → click → smart filename → .md saved

📣 What's New · ⚡ Install · 🚀 Usage · ✨ Demo · 🧠 Naming · 🔧 Features · 📂 Structure · 📌 Notes

English · 简体中文 · 繁體中文 · Español · Deutsch · 日本語 · Русский · Português · 한국어

---

📣 What's new

v1.2.0 — clip-md now speaks three languages

English · 简体中文 · 繁體中文

• Detects the system language while the language setting is auto.
• Switches language from the tray menu and applies it after restart.
• Publishes standalone Windows and macOS builds from GitHub Actions.

See the latest release.

---

🧩 Works with any text you can copy

clip-md listens for non-empty plain text at the clipboard level, so it works across browsers, AI assistants, and most apps. Selected Windows editor processes are suppressed by default to reduce interruptions.

Content	Examples	Saved result
💬 AI responses	Text copied from ChatGPT, Claude, DeepSeek, or another app	UTF-8 .md file
🔬 Research notes	Excerpts, interview notes, reading highlights	UTF-8 .md file
💻 Technical content	Code explanations, lists, Markdown text	UTF-8 .md file
📝 Plain text	Any non-empty clipboard text worth keeping	UTF-8 .md file

The original clipboard text is written to disk without HTML conversion, image extraction, or cloud processing.

---

⚡ Install

Download the latest standalone build:

Platform	Download	First launch
Windows x86-64	Windows download	Download the Windows executable and double-click it; SmartScreen may show an unsigned-app warning
macOS Apple Silicon	macOS download	Download the macOS binary and grant execute permission; Gatekeeper may warn or block it

Pre-built files are standalone executables and do not require Python.

After downloading the macOS build, open Terminal in the download folder, grant the file execute permission with chmod +x, then launch it.

The current macOS release file is ad-hoc signed, has not been notarized, and omits some project-owned icon and translation assets. Run from source when you need the complete repository assets.

🛠 Run from source

Clone the current repository:

git clone https://github.com/okht/clip-md.git
cd clip-md

Windows

py -m venv .venv
.\.venv\Scripts\Activate.ps1
py -m pip install -r requirements.txt
py main.py

macOS

python3 -m venv .venv
source .venv/bin/activate
python -m pip install "PyQt6>=6.6" "keyboard>=0.13" "jieba>=0.42"
python main.py

---

🚀 Usage

The core loop is intentionally small:

Copy → M↓ appears → click → ✓ → Markdown saved

Action	Result
Copy non-empty text	An M↓ bubble appears beside the cursor
Left-click M↓	Saves the clipboard text as a local .md file
Left-click the green ✓	Opens the saved file while the success bubble is still visible
Right-click the bubble	Dismisses it immediately
Hover over the bubble	Pauses the auto-dismiss timer
Wait 3 seconds	The bubble fades automatically
Press Ctrl+Alt+M	Force-saves the current clipboard when the hotkey is available

On first launch, choose a save folder or keep the default subfolder created in your Documents directory.

System tray

Tray action	What it does
Left-click the tray icon	Opens the save folder
Set / open save folder	Changes or opens the destination
Recently unsaved	Keeps up to 5 recently detected items for the current session
Pause / resume	Stops or resumes clipboard-triggered bubbles
Launch at startup	Toggles the current user's startup entry
Language	Switches English / 简体中文 / 繁體中文 after restart
Exit	Closes clip-md and unregisters its hotkey

---

✨ Demo

Imagine copying this text from a browser or AI assistant:

# Retrieval-Augmented Generation

RAG combines retrieval, context assembly, and generation to ground model output.

clip-md keeps the interaction compact:

Clipboard  ❯ Retrieval-Augmented Generation...
clip-md    ❯ M↓
Click      ❯ ✓
Saved      ❯ a smart-named .md file in your chosen folder

A generated filename for this example is:

Retrieval_Generation_Augmented_RAG.md

The exact words depend on the copied text. Existing files are preserved; duplicate names receive _1, _2, and so on.

---

🧠 Smart filenames

clip-md uses a three-stage fallback chain:

Priority	Strategy	Example
1	Extract up to 4 Chinese or English keywords from the first 500 characters	检索_RAG_架构_分析.md
2	Use the first 10 cleaned content characters	RetrievalA.md
3	Use a timestamp	20260404_143022.md

During keyword extraction, clip-md filters common filler phrases, URLs, file paths, emoji, Markdown syntax, stop words, and common code keywords.

Every selected filename is then sanitized to:

• remove characters that are illegal in Windows filenames
• merge repeated underscores and limit the name to 50 characters
• append _1, _2, and later numbers instead of overwriting an existing file

---

🔧 Features

Core loop	Stay focused	Desktop native
Mouse-side save bubble	Event-driven clipboard monitoring	Windows and macOS builds
One-click UTF-8 Markdown save	Suppression for selected editor processes	System tray controls
Smart keyword filenames	Duplicate-content protection	Dark / light system theme
Three-stage filename fallback	Session-only recent queue	High-DPI positioning
Global hotkey when available	Pause / resume monitoring	Launch at startup
Duplicate-name protection	Asynchronous file writes	Three UI languages

🔒 Privacy and safety

Topic	Behavior
Clipboard processing	Runs locally; no external API, telemetry, upload, or auto-update client is used
Saving	Happens after a bubble click, a recent-item selection, or an explicit hotkey action
File content	Writes the original clipboard text as UTF-8 without BOM
Existing files	Never overwritten; duplicate names receive numeric suffixes
Recent items	Keeps at most 5 items in memory and clears them when the app exits
Logging	Records operations and filenames without recording clipboard text
Configuration	Stored in the operating system's standard per-user application data location

---

📂 Project structure

clip-md/
├── main.py                     # application entry point
├── clipboard_monitor.py        # event-driven clipboard watcher
├── bubble_widget.py            # cursor-side save bubble
├── file_saver.py               # asynchronous UTF-8 writer
├── filename_generator.py       # filename fallback chain
├── keyword_extractor.py        # Chinese and English keyword extraction
├── tray_manager.py             # tray menu and global hotkey
├── config_manager.py           # local settings
├── platform_utils.py           # Windows / macOS integrations
├── signal_bus.py               # shared Qt signals
├── i18n.py                     # language routing
├── translations/               # en / zh_CN / zh_TW
├── assets/                     # tray and state icons
├── test_*.py                   # automated tests
└── .github/workflows/          # tagged release builds

The modules communicate through a Qt signal bus, keeping clipboard monitoring, UI, file writing, and tray behavior independently testable.

---

🏗 Build from source

Windows

py -m pip install -r requirements.txt pyinstaller
$spec = Get-ChildItem -Filter *.spec | Select-Object -First 1
py -m PyInstaller $spec.FullName --clean -y

macOS

python -m pip install "PyQt6>=6.6" "keyboard>=0.13" "jieba>=0.42" pyinstaller
python -m PyInstaller --onefile --noconsole --collect-data jieba \
  --add-data "assets:assets" \
  --add-data "translations:translations" \
  --name clip-md main.py

Build output is written to dist/. Tagged pushes trigger the repository's Windows and macOS release workflow.

---

📌 Notes

• Windows and macOS Apple Silicon are the currently published targets.
• Clipboard handling covers plain text. Images, files, HTML-to-Markdown conversion, and rich-text extraction are outside the current scope.
• The default suppression list uses Windows process names for VS Code, Typora, Obsidian, and MarkText; behavior differs on macOS.
• The global hotkey may require Accessibility permission on macOS. The app continues running if hotkey registration fails.
• The Windows executable is unsigned. The macOS build is ad-hoc signed and has not been notarized. SmartScreen or Gatekeeper may ask for confirmation.
• The current release workflow and v1.2.0 macOS package omit some project-owned icon and translation assets; source mode provides the complete repository assets.

---

🗓 Changelog

Version	Date	Highlights
v1.2.0	2026-04-07	English, Simplified Chinese, Traditional Chinese, system-language detection, tray language switcher
v1.1.0	2026-04-04	macOS platform layer and dual-platform release workflow
v1.0.1	2026-04-04	Smart keyword filenames, denoising, sanitization, duplicate handling
v1.0.0	2026-04-04	Clipboard monitoring, mouse-side bubble, tray menu, global hotkey

See every published build on the Releases page.

---

Made for ideas worth keeping.

MIT License © okht