ghostty-use

ghostty-use

在重启前捕获可识别的 Claude Code 和 Codex 终端会话，并在重启后重新打开记录的 ID。手动快照会评估会话是否存活；自动备份会保存恢复元数据，并明确标注覆盖不完整和存活状态未知。

Ghostty 在 macOS 上没有会话恢复 CLI 或 AppleScript 标签页字典（已在 Ghostty 1.3.1 上验证，2026-10-04），因此此技能提供了一套绕过这一限制的实用流程：手动执行 ps 清点 → 按存活状态评级的快照 → 通过粘贴按键恢复 → 自动核对并显示每次粘贴失败。

快照、重建、试运行和核对都可在不占用桌面的情况下进行。实际恢复需要全局键盘和剪贴板输入，即使作为后台 shell 任务启动，也属于前台操作。恢复前，请通过明确的 Ghostty 交接或已有的明确桌面空闲授权获得许可；检查当前活动，并协调好 Agent 的独占操作权。在已有授权的前提下，直接通知并执行，无需再次询问。输入空闲本身不代表拥有操作权。如果桌面正忙或状态未知，请继续准备和只读检查；有人接管时，立即停止输入，绝不要恢复到之前的焦点。主机拒绝仍具有约束力。

入口决策树

你刚才说了什么 / 想做什么	运行
因更新 / 重启准备退出（“重启前保存会话”）	snapshot
定期备份，只保存变更（“定期增量快照”）	阅读 automatic-snapshots.md，然后运行 ghostty_watch.py install --apply
已重启，想恢复之前的标签页（“恢复之前的窗口”）	使用合适的快照；若没有快照或快照已过时，则运行 reconstruct，然后对选定的清单运行 restore --all
“有没有丢失内容？” / 怀疑恢复后有遗漏	check
重新打开某个特定会话	restore --only <id-prefix>
Codex 配额即将用完；手动切换账户，同时保留所有 Codex 工作	阅读 codex-account-switch.md；依次运行 switch-prepare → 手动退出 / 登录 → switch-restore

Codex 账户切换

在用户手动切换 ChatGPT 账户前，保留所有 Ghostty Codex 会话，然后一次性重新打开原有会话 ID。不包括 Claude Code。选择此流程前，请先阅读 codex-account-switch.md。 使用 scripts/ghostty_session.py switch-prepare 和 switch-restore；内置的 scripts/ghostty_switch.py 负责选择固定清单、检查账户 / 进程、避免重复地重试，以及单独报告身份验证状态。

python3 <skill-dir>/scripts/ghostty_session.py switch-prepare
# User: finish work, exit the saved Codex TUIs and manually switch account.
python3 <skill-dir>/scripts/ghostty_session.py switch-restore

默认在一个窗口中使用多个标签页；只有在需要独立窗口时才使用 --layout windows。 交接期间请保留打印出的固定清单。若捕获结果未解决、账户未变更或旧进程仍在运行，则视为交接未完成。此流程绝不会终止进程或切换凭据。实际打开前，请遵守上述前台操作条件；仅当缺少该交接时才询问。--dry-run 和 --check 仍为只读操作。请区分重新打开的 ID 与已成功运行的新账户请求：脚本将身份验证报告为 not_checked，且不会发送测试提示词。

快速开始

# Before quitting (from any directory):
python3 <skill-dir>/scripts/ghostty_session.py snapshot

# After restart (from any directory; needs Accessibility permission for keystrokes):
python3 <skill-dir>/scripts/ghostty_session.py restore        # manual: active only; automatic: full recorded set
python3 <skill-dir>/scripts/ghostty_session.py restore --all  # include waiting/quota/dead/stale/unknown records

快照会保存到 ~/.ghostty-session/snapshots/（相对于主目录，重启后仍会保留）。 报告会涵盖每个存活的 TUI：包括已捕获的会话，以及用于记录尚无转录内容的新标签页的 unresolved 部分——会话数量少于标签页数量的情况会在此处说明，不会悄悄遗漏。 默认情况下，restore 会跳过已存活的 ID。结束时，它会执行范围受限的自动检查，打印 N/M present、手动重新打开命令，以及仅包含缺失 ID 的重试命令。请先查看检查结果，再判断是否成功；每个标签页显示的 SENT (unverified) 表示粘贴已确认，不代表会话确实已重新打开。使用同一份清单重新运行，只会打开仍缺失的 ID。--dry-run 会打印命令，不执行 GUI 操作。

自动备份变更内容

安装或运行 scripts/ghostty_watch.py 前，请先阅读 automatic-snapshots.md。它只保存已更改的恢复状态，并保留所有先前版本。未发生变化的轮次不会写入快照或常规日志。自动清单涵盖 Ghostty 进程的后代进程，不读取对话记录；其存活状态明确标记为未知，且 restore 会选择记录的整个集合。自动清单中没有 UUID 的 TUI 仍无法确定——监视器的有限扫描会刻意避免读取对话记录；手动快照、检查和恢复可以解析这些 TUI（见下方的锚点项目）。 对于部分观测，会保守地保留先前缺失的 ID。监视器不会打开应用或标签页。手动快照仍默认只恢复活动项。

没有合适的快照：重建恢复清单

对于 Codex 身份识别和索引恢复，请使用维护中的 daymade-claude-code:read-codex-history 依赖项。根据当前主机解析该 Skill 的目录；如果尚未安装且已获授权，请通过主机常规的市场流程安装其 daymade-claude-code 插件。脚本会查找源码检出目录或单独安装的同级 read-codex-history；其他目录布局请使用 --history-reader <reader-skill-dir> 或 GHOSTTY_CODEX_HISTORY_READER。如果缺少 reader 或状态索引，脚本会明确报错；请勿用扫描 rollout 集合代替。

# Review candidates without writing state or opening tabs:
python3 <skill-dir>/scripts/ghostty_session.py reconstruct \
  --history-reader <reader-skill-dir> --recent-hours 72 --limit 100 --dry-run

# Build one chosen set in a NEW file; --only accepts unambiguous ID prefixes:
python3 <skill-dir>/scripts/ghostty_session.py reconstruct \
  --history-reader <reader-skill-dir> --since <YYYY-MM-DD> \
  --only <id-prefix-1> <id-prefix-2> --out <recovery-manifest.json>

# Restore the full selected set in one invocation, including waiting/quota rows:
python3 <skill-dir>/scripts/ghostty_session.py restore \
  --snapshot <recovery-manifest.json> --all

重建会将可选的 --snapshot（否则使用最新快照，如果存在）与有限范围内近期索引的 Codex 候选项合并。它会使用所属 reader 验证内部 rollout 身份，并将每一行标记为 past-snapshot 或 indexed-terminal-candidate。终端证据为 source=cli 或 originator=codex-tui。实际 TUI 可能会报告 source=vscode。--terminal-source 和 --terminal-originator 可自定义接受的元数据值。子 Agent 会根据所属清单中的元数据排除，而不是根据文件名中的下划线排除。--codex-home 用于选择非默认的 Codex 存储目录。

过去曾出现在快照中，只能证明某个会话曾被该快照记录。索引中的终端候选项只能证明其来自终端，不能证明关机时相应标签页处于活动状态。恢复前请检查时间戳和标题，并选择预期的集合。--limit 是检查索引候选项数量的硬上限；仅在需要时才扩大搜索范围。 没有快照时，Claude 会话的成员身份仍然未知； 重建不会发现 Claude 会话。请保留已知快照中的明确 Claude 记录，不要声称恢复结果完整无遗漏。

新清单不会修改 snapshots/latest.json，并且会拒绝覆盖已有输出。退出码 0 表示已验证所选证据；退出码 1 表示清单列出了需要关注的已拒绝候选项；退出码 2 表示输入无效或证据不可用。试运行输出为 JSON，供检查使用。

手动快照按会话记录的内容

• 锚点：存在时，使用进程命令行中的会话 UUID（绝不按进程名称匹配——argv[0] 会在裸 claude 和 /usr/local/bin/claude 之间切换，按名称匹配曾在 2026-10-04 造成两次误报，称所有会话都已消失）。全新的 TUI 在 argv 中不带 UUID（只有恢复/分叉时才会写入），因此改为从转录存储中锚定：在进程启动时或之后创建、位于相同 cwd 的项目存储桶中的会话文件，并验证其内部身份（2026-10-07：25 个活动会话中有 11 个是全新的 TUI，仅按 argv 匹配时不可见）。多个全新 TUI 共用一个存储桶时，会话转录会被互不重叠地分配——每个 TUI 对应一个文件；若出现无法判定的竞争情况（认领距离相同），则将其列入未解决部分，而不是猜测。两种方式都无法匹配的活动 TUI，会以未解决行的形式显示在快照报告中——明确可见，不会悄然丢弃。
• 活动状态：从会话文件的内容读取最后一次真实交互时间——而不是文件 mtime（空闲 TUI 仍会持续触碰文件；2026-10-04，一条“今天下午仍活动”的判断与文件内时间戳相矛盾，后者显示会话于 03:21 结束）。
• 通道健康状态：当 Claude 转录末尾包含结构化的 isApiErrorMessage，且内容为 "Login expired" 时，标记为 dead-channel——恢复此类标签页会重新打开历史记录，但会话会停在 /login；快照会标记出来，方便跳过。对话中仅仅讨论某个错误的文字不计入（在此规则制定之前，一个曾讨论过 "Login expired" 的健康会话被错误分类）。
• 配置文件：存在时，从 --settings .../settings/<name>.json 解析；否则为 direct。

恢复机制与限制

• 重新打开 = 激活 Ghostty → Cmd+T → 将重新打开命令粘贴自剪贴板 → Return；每个缺失的会话对应一个标签页，之后必须自动重新核对。按键粘贴对时序很敏感：若在 Cmd+T 和粘贴之间受到干扰，就会留下一个空标签页，命令也会悄然丢失（2026-10-04 实测）。自动检查就是为了让这种情况可见；切勿跳过，也绝不能只凭粘贴的返回代码就宣告成功。
• 粘贴前，告知用户在重新核对完成前不要触碰键盘或鼠标。脚本会在首次 GUI 操作前再次显示此提示。
• osascript 按键操作（System Events）需要辅助功能权限。如果当前主机拒绝 Ghostty UI 自动化，切勿切换通道绕过：准备好选定的清单和准确的用户执行恢复命令，然后在用户运行后，使用只读的 check --snapshot <manifest> --strict。
• 窗口分组无法恢复——Ghostty 的 macOS 辅助功能界面不提供标签页到窗口的映射。所有标签页都会在同一个窗口中重新打开；如有需要，请手动重新排序。
• codex 自身已无法找到的 rollout 文件会显示 no-artifact；恢复这些文件时会重放相同的 codex resume <id>，且只能尽力而为。

配置文件环境映射（可选）

如果 Claude 配置文件通过环境变量注入配置（例如 CLAUDE_CONFIG_DIR），请将前缀记录在 ~/.ghostty-session/profile-env.json 中，以便恢复的标签页以相同的配置文件上下文启动：

{"research": "CLAUDE_CONFIG_DIR=~/.claude-profiles/research", "family": "HTTP_PROXY=http://127.0.0.1:7890"}

如果没有此映射，恢复时会重放捕获的设置、配置文件以及权限/模型标志；除 argv 以外的进程环境仍未知。此映射是用户本地数据，位于技能包之外；不会随附默认映射。

故障排除

症状	原因 / 解决方法
restore 报告 STILL MISSING	运行输出的仅针对缺失项的重试命令，或在新标签页中手动运行准确的重新打开命令
Codex 会话出现 no-artifact	已验证的索引会话没有可用的 rollout；恢复仍尽力而为
Codex 存活状态为 unknown	读取器 / 索引不可用或身份不明确；应解决依赖项 / 存储问题，而不是选择第一个文件名匹配项
dead-channel 会话仍被恢复	这是预期行为：历史记录会重新打开，会话会停在 /login；请重新进行身份验证或切换提供商
check 显示存在，但标签页看起来是空的	另一个运行中的进程已占用该会话 ID（例如，已在另一个标签页中恢复）
osascript 拒绝按键操作	授予 Accessibility（System Events）权限；使用 osascript -e 'tell application "System Events" to get UI elements enabled' 验证
会话列表中缺少全新标签页	新启动的 TUI 没有 argv UUID，其 transcript 文件会在收到第一条消息后出现；在此之前，它会显示在未解析的运行中 TUI 下。如果第一条消息在标签页打开 20 分钟以上后才发送，创建时间窗口已过，按设计该标签页会一直处于未解析状态

深入了解

• references/session_liveness.md — 存储布局 （Claude 项目 / Codex 会话）、transcript 结构、恢复分叉命名、 存活状态规则及其背后的误分类情况。当存活状态结果看起来不正确，或布局在应用更新后发生变化时，请阅读此文档。
• references/restore_mechanics.md — Ghostty 为何没有 CLI/AX 恢复路径、按键粘贴协议、协调设计， 以及窗口分组边界。修改恢复路径前请阅读此文档。