Persistent Code Terminal

核心用法

persistent-code-terminal 是一个专为 AI 编程设计的 tmux 会话管理框架，解决传统终端在 AI 辅助编码中的状态丢失问题。核心遵循 start → send → read → decide 四步模型：

1. start.sh：创建或附加到 <project-name>-code-session 会话
2. send.sh：发送单条命令，支持 --timeout、--phase 等参数，自动追加 __PCT_EXIT_CODE__N 哨兵标记
3. read.sh：解析哨兵，更新 .pct-state.json 状态文件
4. status/summary.sh：快速获取执行状态与最近 120 行输出摘要

Codex 优先工作流通过 codex-exec.sh 实现，封装 codex exec --full-auto --sandbox workspace-write，支持指令级自然语言驱动。

智能路由系统

• 自动触发：autoCodeRouting 配置启用后，通过 persistent-code-terminal-route.sh 进行意图识别（code/fix/test/build/commit/push 等）
• 多项目支持：单条消息可按 ； 或换行分割多项目任务，串行执行
• 快捷指令：消息以 codex 开头时，自动路由至 codex-exec 流程

显著优点

• 会话持久化：detach/reattach 不丢输出，长时任务（dev server、watch mode）持续运行
• 移动端/SSH 友好：解决网络中断导致的状态丢失
• 结构化输出：--json 模式便于程序解析，.pct-state.json 提供机器可读状态
• 安全过滤：内置 git 仓库检测、动作动词白名单、不要执行，只分析 绕过机制
• 依赖兜底：doctor.sh 自动诊断 tmux/codex 缺失问题

潜在局限

• tmux 强依赖：目标系统必须预装 tmux，Windows 原生环境需 WSL
• Codex CLI 生态绑定：最优体验需 OpenAI Codex CLI，其他 CLI 工具需自定义封装
• 沙箱限制：--sandbox workspace-write 虽提升安全，但可能限制某些系统级操作
• 串行执行瓶颈：多项目任务按序执行，无内置并行调度
• 状态文件污染：.pct-state.json 位于项目目录，可能误提交（建议加入 .gitignore）

适用人群

• 远程服务器 / 云开发环境开发者
• 移动端 SSH 场景下的 AI 辅助编程用户
• 需要长时间保持开发服务（热重载、测试 watcher）运行的团队
• 追求「自然语言 → 代码变更 → 提交推送」全自动链路的技术早期采用者

常规风险

| 风险类型 | 说明 | 缓解措施 |

|---------|------|---------|

| 强制推送 | 默认禁止 `git push --force`，但用户显式指令可绕过 | 代码审查策略兜底 |

| 密钥泄露 | 终端输出可能捕获环境变量或凭据 | 敏感操作前检查 `env` 输出，使用 secret 管理工具 |

| 分支污染 | 直接推 main/master 需显式确认 | 团队级分支保护规则 |

| 无限循环 | `--max-retries 3` 限制自动重试，但复杂指令仍可能逻辑死循环 | 人工介入检查点 |

| tmux 会话堆积 | `list.sh` 可查看，但无自动清理机制 | 定期手动清理或 CI 策略补充 |

核心用法

persistent-code-terminal 是一个专为 OpenClaw/Claude Code 设计的 tmux 包装器，为每个项目创建独立的持久化终端会话（<project-name>-code-session）。核心工作流遵循 start → send → read → decide 四步模型：先启动会话，发送单条命令，读取输出结果，再决定下一步操作。

主要脚本包括：start.sh 创建/恢复会话、send.sh 发送命令并支持超时控制、read.sh 解析执行结果、status.sh 快速查看状态、summary.sh 获取最近 120 行输出摘要。对于 Codex CLI 用户，codex-exec.sh 可直接执行自然语言指令，自动处理 --full-auto --sandbox workspace-write 等参数。

智能路由功能（默认关闭）支持用自然语言驱动开发工作流，可识别 "修复"、"测试"、"构建"、"提交" 等意图，并支持多项目并行处理。所有状态保存在本地 .pct-state.json，便于跨会话恢复。

显著优点

网络韧性：tmux 会话在 SSH 断开或移动端切换后依然存活，重新连接即可恢复完整上下文，彻底解决移动开发、远程办公中的网络不稳定问题。

状态连续性：shell 环境变量、工作目录、后台进程（如 dev server、watch mode）在多次 AI 对话间保持连续，无需反复初始化项目环境。

AI 原生集成：深度适配 Codex CLI，支持自然语言指令直接转化为代码操作，同时保留完整的人工审核与 --dry-run 预览机制。

极简依赖：纯 Bash 实现，零第三方代码依赖，仅需系统包管理器安装的 tmux，在 macOS 和 Linux 上开箱即用。

安全可控：命令执行通过隔离的 tmux 会话进行，敏感操作需用户显式确认，无隐藏网络调用，无硬编码密钥。

潜在缺点与局限性

平台限制：仅支持 macOS 和 Linux，Windows 用户需借助 WSL 或虚拟机。

学习曲线：tmux 本身有概念门槛（pane、window、session），不熟悉终端复用的用户需要时间适应。

功能边界：本质仍是命令执行包装器，复杂 IDE 功能（调试器、智能跳转、图形化 diff）需配合其他工具。

自动路由风险：虽然默认关闭且有多层过滤，但启用后仍需警惕自然语言指令的歧义解读，建议在受信任仓库中使用。

状态文件污染：.pct-state.json 和 .pct-routing.log 会写入项目目录，需手动加入 .gitignore 避免误提交。

适合的目标群体

• 远程/移动开发者：经常通过 SSH 或移动设备接入，需要会话在网络波动中保持存活
• AI 辅助编程用户：使用 Codex CLI、Claude Code 等工具，希望自然语言指令能可靠执行并保留上下文
• 多项目并行工作者：需要同时管理多个代码库的终端环境，快速切换而不混淆状态
• 终端优先的工程师：习惯命令行工作流，追求轻量、可脚本化的开发环境

使用风险与注意事项

命令执行风险：作为终端工具，本质能力是执行用户指定的 shell 命令。虽有 --dry-run 和超时控制，但仍需警惕误操作（如错误的 rm -rf、意外的 git push --force）。建议关键操作前先预览，避免在生产环境直接试用新指令。

自动路由误触发：若启用 autoCodeRouting，自然语言消息可能被意外解析为可执行指令。多层过滤（git 仓库检查、动作动词检测、中文绕过指令 "不要执行，只分析"）可降低风险，但敏感场景建议保持关闭。

状态文件隐私：.pct-state.json 包含项目路径和命令历史，虽无敏感凭证，但在共享环境或开源项目中仍需注意信息泄露。建议定期清理日志文件。

tmux 版本兼容性：依赖系统 tmux，老旧版本（< 2.1）可能不支持某些捕获功能。安装脚本已覆盖 Homebrew 和 apt，但企业内网环境可能需要手动处理依赖。

长任务资源占用：持久会话中的后台进程（如未关闭的 dev server）会持续消耗系统资源，建议通过 list.sh 定期检视活跃会话，及时清理不再需要的终端。