codex-snapshots 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ffffhx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# Codex Snapshots
+
+面向 Codex、Claude Code 和 Trae 的本地优先、只读会话快照工具。
+
+这个项目从 Garden Lab 中拆分出来，让会话快照查看器可以作为独立工具使用。它会扫描本地 agent 历史记录，在浏览器中提供审阅界面，导出静态 HTML/Markdown 快照，自动脱敏常见密钥，并支持把已脱敏的快照发布到一个轻量的独立分享 API。
+
+网站：<https://ffffhx.github.io/codex-snapshots/>
+
+## 快速开始
+
+不需要克隆仓库，可以直接通过 npm 临时运行：
+
+```bash
+npx codex-snapshots@latest serve --port 4321
+```
+
+打开 <http://127.0.0.1:4321/>。
+
+也可以全局安装：
+
+```bash
+npm install -g codex-snapshots
+codex-snapshot serve --port 4321
+```
+
+要求 Node.js 18 或更高版本。
+
+## 从源码运行
+
+```bash
+pnpm install
+pnpm dev
+```
+
+打开 <http://127.0.0.1:4321/>。
+
+如果想在本地预览公开静态网站：
+
+```bash
+pnpm site:dev
+```
+
+打开 <http://127.0.0.1:4323/>。
+
+## 命令行
+
+全局安装或通过 `npx` 使用时：
+
+```bash
+codex-snapshot list --source all
+codex-snapshot preview <session-id>
+codex-snapshot export <session-id> --html --output snapshot.html
+codex-snapshot export <session-id> --md --output snapshot.md
+codex-snapshot serve --port 4321
+codex-snapshot record-trae --port 4732
+```
+
+从源码运行时，也可以使用对应的 pnpm 脚本：
+
+```bash
+pnpm snapshot list --source all
+pnpm snapshot preview <session-id>
+pnpm snapshot export <session-id> --html --output snapshot.html
+pnpm snapshot export <session-id> --md --output snapshot.md
+pnpm snapshot serve --port 4321
+pnpm snapshot record-trae --port 4732
+```
+
+默认读取以下目录：
+
+- Codex：`$CODEX_HOME` 或 `~/.codex`
+- Claude Code：`$CLAUDE_HOME` 或 `~/.claude`
+- Trae：`$TRAE_HOME` 或 `~/.trae-cn`
+- Trae 应用数据：`$TRAE_APP_HOME` 或 `~/Library/Application Support/Trae CN`
+
+## 云端分享服务
+
+启动可选的分享 API：
+
+```bash
+SNAPSHOT_SHARE_TOKEN=change-me codex-snapshot-share
+```
+
+如果还没有全局安装，可以用：
+
+```bash
+SNAPSHOT_SHARE_TOKEN=change-me \
+npx -p codex-snapshots@latest codex-snapshot-share
+```
+
+从源码运行：
+
+```bash
+SNAPSHOT_SHARE_TOKEN=change-me pnpm share:server
+```
+
+发布已脱敏的快照：
+
+```bash
+SNAPSHOT_SHARE_TOKEN=change-me \
+codex-snapshot publish <session-id> \
+  --api-url http://127.0.0.1:8787 \
+  --site-url http://127.0.0.1:8787
+```
+
+服务端默认把分享内容保存在 `.codex-snapshots/shares.json`。如果需要使用其他路径，可以配置 `SNAPSHOT_SHARE_DATA_FILE`。
+
+## macOS LaunchAgent
+
+从源码运行时，可以把本地查看器安装为用户级 LaunchAgent：
+
+```bash
+pnpm snapshot:install-daemon
+pnpm snapshot:daemon:status
+pnpm snapshot:daemon:logs
+pnpm snapshot:uninstall-daemon
+```
+
+安装后，LaunchAgent 会在登录后保持 <http://127.0.0.1:4321/> 可用。
+
+## 安全模型
+
+- 默认导出用户和助手消息。
+- 跳过 developer、system 和 bootstrap 消息。
+- 除非传入 `--include-tools`，否则隐藏工具调用。
+- 除非传入 `--include-tool-output`，否则隐藏工具输出。
+- 自动脱敏常见密钥、Bearer token、JWT、私钥块、Cookie 和本地 home 路径。
+- 生成静态、只读快照；接收方无法恢复或操作原始 agent 线程。
+- 除非显式允许，否则拒绝把未脱敏快照发布到云端。
+
+脱敏器会尽量保守处理，但并不完美。分享前请务必查看风险面板。