| name | tampermonkey-cli |
| description | 通过 Tampermonkey Editors 管理浏览器里的 Tampermonkey userscript；适用于需要从 Codex 安装、更新、读取、列出或删除本机油猴脚本，或把本地 .user.js 同步到 Tampermonkey 时使用。 |
通过 Tampermonkey Editors 的本地 WebSocket 协议管理浏览器里的 userscript。
调用约定
说明：以下脚本调用均以当前 SKILL.md 所在文件夹为 workdir。
脚本调用方式必须直接当作可执行命令运行，不要用 uv run python 或 python：
cd skills/tampermonkey-cli
./scripts/tampermonkey.py --help
错误示例：
uv run python skills/tampermonkey-cli/scripts/tampermonkey.py --help
python skills/tampermonkey-cli/scripts/tampermonkey.py --help
工作流
- 确认浏览器已安装 Tampermonkey 和 Tampermonkey Editors。
- 启动常驻桥接：
./scripts/tampermonkey.py serve
- 把输出的
Tampermonkey Editors connection code 输入 Tampermonkey Editors。
- 保持
serve 进程运行。
- 在其它 shell 或后续 Codex 命令中复用默认 socket 调用：
./scripts/tampermonkey.py status
./scripts/tampermonkey.py list
./scripts/tampermonkey.py get '<script-path>/source' --output /tmp/example.user.js
./scripts/tampermonkey.py put /path/to/example.user.js
./scripts/tampermonkey.py patch '<script-path>/source' /path/to/example.user.js
Socket 约定
- 控制面使用 Unix Domain Socket，不使用 localhost HTTP。
- 默认 socket 路径优先使用
$XDG_RUNTIME_DIR/codex-tampermonkey.sock。
- 如果
$XDG_RUNTIME_DIR 不存在，则使用 $XDG_CACHE_HOME/codex/codex-tampermonkey.sock。
- 如果
$XDG_CACHE_HOME 也不存在，则使用 ~/.cache/codex/codex-tampermonkey.sock。
- 需要覆盖默认路径时，所有命令都支持
--socket <path>。
命令
serve：启动桥接进程，打印一次 connection code，并持有 Tampermonkey Editors 连接。status：查看 serve 是否存在、Tampermonkey Editors 是否已连接。list：列出浏览器中已安装的 userscript；支持 --pattern 和重复的 --include-pattern。get <path> --output <file>：读取脚本内容并写入本地文件；path 来自 list 输出。不要直接把脚本文本输出到终端。put <file>：创建新 userscript。patch <path> <file>：用本地文件覆盖已有 userscript。delete <path>：删除指定 userscript。shutdown：请求 serve 进程退出。
注意事项
serve 只生成一次 connection code；后续命令通过同一个 socket 复用连接。path 是 Tampermonkey Editors 返回的内部路径，通常形如 <script-id>/source，不要自己猜。get 必须指定 --output；读取后用 sed、rg、diff、编辑器等常规文件工具查看内容。put、patch 和 delete 会修改浏览器里的 Tampermonkey 脚本；执行前确认目标文件内容是最终版本。- 如果
put 或 delete 返回 405 Method Not Allowed，这是 Tampermonkey Editors 端拒绝该 action；先在 Tampermonkey UI 中手动创建脚本，再用 list 找到 path，并用 patch 覆盖内容。
- 如果命令提示无法连接 socket，先运行
serve 并完成 Tampermonkey Editors 连接。
