What is Clipth AGENTS.md?

A development guide for Clipth, a native macOS menu-bar clipboard manager. It documents the app's SwiftUI and SwiftData structure, local features, build process, and code-signing precautions.

Use it when building, running, changing the interface, signing, or releasing Clipth.

It gives the coding agent the product context and rules needed to change the app without breaking its shared data model or release workflow.

Clipth AGENTS.md — Instructions file by wavever

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods

npx agentmods add instructions/wavever/clipth/agents-md

Clone the repo

git clone --depth 1 https://github.com/wavever/Clipth

Made for: Codex, OpenCode.

Per session 2,683 This file is loaded in full into every session.

When invoked 2,683 The same file — it is already loaded in full.

Security scan A 0 findings. Scan, not verified.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5	$0.02683	$0.02683
Opus 5	$0.01341	$0.01341
Sonnet 5	$0.00537	$0.00537
Haiku 4.5	$0.00268	$0.00268

Measured 2d ago against content hash 256060f96156, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

Clipth AGENTS.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

AGENTS.md · 166 lines

How it starts

The opening of the file, as written. The whole thing — 166 lines — stays where its author put it; the contents beside it link to each section on GitHub.

AGENT.md

给 AI 助手（以及人类）在本仓库工作时的指引。构建、发布、改 UI 之前先读这份。

这是什么

剪迹 / Clipth —— 原生 macOS 菜单栏剪贴板管理器。

SwiftUI + SwiftData (SQLite)，macOS 14.0+，Swift 5（Xcode 16）。
Bundle id com.wavever.clipth；仓库 wavever/Clipth。
默认本地 / 离线：语义搜索用 Apple NLEmbedding，OCR 用 Vision，本地 MCP 服务走 stdio。无遥测；网络仅用于 Sparkle 更新检查和用户主动配置的端到端加密同步（iCloud 云盘 / WebDAV / 本地同步文件夹）。
依赖（SPM）：Sparkle（自动更新）、KeyboardShortcuts（全局快捷键）。

目录结构

Clipth/
  Models/       SwiftData @Model 类型 + 偏好存储（AppearancePreferences 等）
  ViewModels/   ClipboardViewModel（列表/搜索/选择的核心）
  Views/        SwiftUI 视图 + Theme.swift（设计系统）
  Services/     单例：ClipboardMonitor、QuickPasteController、AutoPasteService、
                ToastCenter、Localization、MCPServer、UpdaterService 等
scripts/        generate-signing-cert.sh（一次性签名配置）
.github/workflows/  ci.yml（PR 构建）、release.yml（按 tag 发布）

约定：UI 与服务单例都是 @MainActor，以 .shared 暴露。SwiftData 统一走 AppContainer.shared 这唯一一个 ModelContainer（见 QuickPasteController.swift），保证浮动面板和主窗口读写同一份数据。代码注释解释为什么而非做了什么——改代码时保持同样的注释密度。

本地构建运行

xcodebuild -project Clipth.xcodeproj -scheme Clipth -configuration Debug \
  -derivedDataPath build build
open build/Build/Products/Debug/Clipth.app

准则：开发阶段，每次完成代码开发后都必须构建并把 App 运行起来。 不要只报告编译通过；构建失败就先修复，不算“完成”。构建成功后先杀掉旧实例，再启动刚生成的 .app，在真实 App 里验证：

pkill -f "Clipth.app/Contents/MacOS/Clipth" || true
open build/Build/Products/Debug/Clipth.app

若本次构建使用了不同的 -derivedDataPath 或 Xcode 默认 DerivedData，必须启动对应路径下最新生成的 Clipth.app，不要启动旧产物。

本地构建会自动用 Clipth Self-Signed 身份签名（见下）。若该身份不在钥匙串里，构建会失败——要么运行一次 scripts/generate-signing-cert.sh，要么用 CODE_SIGNING_ALLOWED=NO 做无签名构建。

代码签名（动签名相关的任何东西前必读）

App 使用固定的自签名证书（CN = Clipth Self-Signed）签名，而不是 ad-hoc。这是关键，不能退回 ad-hoc：

macOS 把**辅助功能（TCC）**授权绑定在 bundle 的代码签名*指定要求（designated requirement）*上。ad-hoc 签名会让这个要求退化成每次构建都变的 cdhash，于是每次重建/更新都会静默作废授权，而系统设置里的开关还亮着 → App 不断弹「想要使用辅助功能控制这台电脑」。固定证书让要求变成 identifier + 证书指纹，在重建、更新、换机器后都保持不变，授权得以保留。
ENABLE_HARDENED_RUNTIME = NO。真实签名（不同于 ad-hoc）会真正启用硬化运行时，进而打开库校验，导致启动崩溃（Xcode 16 的 *.debug.dylib / 框架 Team-ID 不匹配）。硬化运行时只有公证才需要，而免费自签名阶段并不公证。只有在升级到 Developer ID + 公证时才重新开启它。

Read the full file on GitHub · 166 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

2d ago First seen · 166 lines · 2,683 tokens per session scan A 256060f96156

Subscribe to this mod's changes

Clipth AGENTS.md is an instructions file published in the GitHub repository wavever/Clipth (23 stars, last pushed 14d ago), licensed MIT. It adds 2,683 tokens to every session, about $0.0134 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.

Data and AI ai-tools clipboard-history clipboard-manager local-first macos mcp

Clipth AGENTS.md

Getting it into your agent

What it costs to keep this loaded

Grade A, and why

Nothing flagged

How it starts

AGENT.md

这是什么

目录结构

本地构建运行

代码签名（动签名相关的任何东西前必读）

What this file has done since we first saw it

Other instructions, from other repositories

TokenPilot AGENTS.md

TokenPilot CLAUDE.md

token-monitor AGENTS.md

personal-model AGENTS.md

humla CLAUDE.md

token-monitor CLAUDE.md