<img src="avatar.svg" width="160" height="160" alt="CliClip Logo" /> <h1 align="center">CliClip</h1> Your clipboard bridge for terminal AI workflows. Paste images as short <code>/tmp/.cc/...</code> paths in terminal, restore the original image in GUI apps. <a href="#english">English</a> · <a href="#zh">中文</a>

English

CliClip detects when you switch into iTerm2 or Terminal and turns the current clipboard image into a short file path like /tmp/.cc/cc_h8x2w9k3zl.png. When you switch back to GUI apps such as WeChat, Chrome, or Slack, it restores the original image to the clipboard.

Features

Context-aware image-to-path conversion in iTerm2, iTerm, and Terminal
Unique temp file per image, so later screenshots do not overwrite earlier pasted paths
Hidden temp directory with short path output, such as /tmp/.cc/cc_h8x2w9k3zl.png
Automatic image restore when you leave the terminal
Smart filtering to avoid interfering with file copies or rich text clipboard content
No extra dependencies beyond macOS native tools and /usr/bin/python3
Automatic downscaling of large images to 1280px to reduce upload size and token usage

Installation

Run the installation script:

curl -fsSL https://raw.githubusercontent.com/ErzhanChen/CliClip/main/scripts/install.sh | bash

The installer will:

Download the latest daemon script
Install it into ~/.cliclip
Register and start the macOS LaunchAgent automatically

When you first copy an image and switch to your terminal, macOS may ask for permission to let your terminal control System Events. Click Allow.

Usage

Copy or screenshot an image.
Switch to iTerm2 or Terminal.
Paste with Cmd+V.
CliClip will paste the latest image path, for example /tmp/.cc/cc_h8x2w9k3zl.png.
Switch back to a GUI app and paste again to get the original image.

Notes:

CliClip keeps up to 20 temp images at a time.
Older temp files are deleted first when the limit is exceeded.
Copying non-image content will not invalidate previously pasted image paths.
Temp files are cleared when the daemon exits.

Uninstallation

launchctl unload ~/Library/LaunchAgents/com.cliclip.daemon.plist
rm ~/Library/LaunchAgents/com.cliclip.daemon.plist
rm -rf ~/.cliclip

简体中文

CliClip 是一个面向 macOS 终端工作流的轻量级剪贴板增强工具。当前台应用切换到 iTerm2 或 Terminal 时，它会把剪贴板中的图片自动转换成短路径，例如 /tmp/.cc/cc_h8x2w9k3zl.png；切回微信、Chrome、Slack 等图形界面应用后，又会把原始图片恢复回剪贴板。

功能特性

在 iTerm2、iTerm 和 Terminal 中自动把图片转换为路径
每张图片都会生成独立的临时文件，后续截图不会覆盖之前已经粘贴出的路径
临时图片保存在隐藏目录中，输出路径简短，例如 /tmp/.cc/cc_h8x2w9k3zl.png
离开终端后会自动恢复原始图片内容
智能过滤文件复制、富文本和 HTML 等剪贴板内容，避免误干扰
不依赖额外运行时，只使用 macOS 原生工具和 /usr/bin/python3
大图会自动压缩到 1280px，减少上传体积和模型 token 消耗

安装方式

直接运行安装脚本即可：

curl -fsSL https://raw.githubusercontent.com/ErzhanChen/CliClip/main/scripts/install.sh | bash

安装脚本会自动完成以下操作：

下载最新的守护进程脚本
安装到 ~/.cliclip
自动注册并启动 macOS LaunchAgent

第一次复制图片并切换到终端时，macOS 可能会弹出权限提示，请允许终端控制 System Events。

使用方法

复制一张图片，或者先截图。
切换到 iTerm2 或 Terminal。
按 Cmd+V 粘贴。
CliClip 会粘贴最新图片对应的路径，例如 /tmp/.cc/cc_h8x2w9k3zl.png。
再切回图形界面应用粘贴时，会恢复为原始图片内容。

说明：

CliClip 最多会保留 20 张临时图片。
超过上限后，会优先删除最旧的临时文件。
复制非图片内容时，之前已经粘贴出去的图片路径仍然可用。
守护进程退出时，会清理这些临时文件。

卸载

launchctl unload ~/Library/LaunchAgents/com.cliclip.daemon.plist
rm ~/Library/LaunchAgents/com.cliclip.daemon.plist
rm -rf ~/.cliclip

Logo & Design

The CliClip logo represents the seamless fusion of terminal efficiency and visual workflows:

Terminal Soul: The deep dark background (#1E1E1E) and prompt symbols (> and _) anchor the tool in the developer's native environment.
The Clip Bridge: The rounded > icon mimics a paperclip, symbolizing the transformation bridge between "Image" and "Path."
Path of Connection: The dashed line at the bottom hints at the underlying file paths that make this integration possible.

License

MIT. See LICENSE.

CliClip

Install / Use

README