dchu917/ctx 源码：https://github.com/dchu917/ctx # ctx Claude Code 与 Codex 的本地上下文管理器。保持精确的会话绑定，干净地恢复工作，分支上下文而不串流，并可选择在本地浏览器前端查看已保存的工作流。 text Claude Code 聊天 Codex 聊天 | | v v /ctx ... ctx ... \ / v v +----------------------+ | 工作流: feature-audit | | claude: abc123 | | codex: def456 | +----------------------+ | +--> feature-audit-v2 分支 ## 为何用 ctx - 精确记录绑定：每个内部 ctx 会话都能绑定到产生它的 Claude 和/或 Codex 对话。 - 无记录漂移：后续拉取始终停留在该绑定会话，而不会跳到磁盘上最新的聊天。 - 安全分支：从另一个工作流的当前状态新建工作流，无需共享后续拉取或劫持原会话。 - 索引检索：已保存的工作流、会话与条目均被索引，支持 ctx search 快速查找。 - 精选加载：固定条目使其始终加载，排除条目使其可搜索但不再回传给模型，或彻底删除。 - 纯本地：无需 API 密钥，无托管服务，只用 SQLite 与本地文件。 ## 快速安装 克隆仓库并执行项目本地安装： bash git clone https://github.com/dchu917/ctx.git cd ctx ./setup.sh 这是面向开发者的主要安装方式，会完成以下操作： - 创建 ./.contextfun/context.db - 写入 ./ctx.env - 将仓库版 ctx shim 安装到 ~/.contextfun/bin - 将本地技能链接到 ~/.claude/skills 与 ~/.codex/skills 适用于： - 想在本地保留仓库副本 - 让 ctx 默认使用项目级数据库 - 正在开发或修改本仓库 ## 4 步演示 1. 克隆并安装： bash git clone https://github.com/dchu917/ctx.git cd ctx ./setup.sh 2. 新建工作流： Claude Code： text /ctx start feature-audit --pull Codex 或终端： bash ctx start feature-audit --pull 3. 理解 --pull： - ctx start feature-audit --pull 创建工作流，并把当前对话的已有上下文拉取进去。 - ctx start feature-audit 仅从当前点开始创建工作流，不补录更早的对话。 4. 稍后继续或分支： Claude Code： text /ctx resume feature-audit /ctx branch feature-audit feature-audit-v2 Codex： bash ctx resume feature-audit ctx branch feature-audit feature-audit-v2 ## 日常使用 Claude Code： - /ctx：显示当前仓库的工作流，或提示尚未设置。 - /ctx list：列出已保存的工作流，当前仓库优先。 - /ctx search dataset download：搜索已保存的工作流与条目。 - /ctx start my-stream --pull：创建工作流并拉取当前对话上下文。 - /ctx resume my-stream：继续某工作流，并把新上下文追加进去。 - /ctx rename better-name：重命名当前工作流。 - /ctx rename better-name --from old-name：直接重命名指定工作流。 - /ctx delete my-stream：删除该工作流最新保存的会话。 - /ctx curate my-stream：打开该工作流的记忆整理界面。 - /ctx branch source-stream target-stream：从另一工作流当前状态派生新工作流。 - /branch source-stream target-stream：Claude 快捷分支命令。 Codex： - ctx：显示当前仓库的工作流。 - ctx list：列出已保存的工作流。 - ctx list --this-repo：仅列出与当前仓库关联的工作流。 - ctx search dataset download：搜索工作流与条目。 - ctx search dataset download --this-repo：仅搜索当前仓库的工作流。 - ctx web --open：打开可选本地浏览器界面，用于浏览、搜索与复制续写命令。 - ctx start my-stream：从当前点创建工作流。 - ctx start my-stream --pull：创建工作流并先拉取当前对话上下文。 - ctx resume my-stream：继续某工作流。 - ctx resume my-stream --compress：以更小包继续工作流。 - ctx rename better-name：重命名当前工作流。 - ctx rename better-name --from old-name：直接重命名指定工作流。 - ctx delete my-stream：删除该工作流最新会话。 - ctx curate my-stream：打开记忆整理界面。 - ctx branch source-stream target-stream：派生新工作流。 注意：Codex 目前不支持仓库自定义斜杠命令，因此请使用安装好的 ctx 命令。当 ctx start、ctx resume 或 ctx branch 加载上下文时，会打印工作流简介、目标会话及最近条目，并提示在 Codex 可用 ctrl-t 查看完整输出，在 Claude 可展开工具块，同时建议代理简要总结并询问如何继续，而不是回贴完整内容。 ## 其他安装方式 ### 克隆仓库并执行全局安装 bash git clone https://github.com/dchu917/ctx.git cd ctx ./setup.sh --global 与快速安装相同脚本，但将固定全局版安装到 ~/.contextfun，而非把当前克隆作为运行时。 ### 不克隆直接全局安装 bash curl -fsSL https://raw.githubusercontent.com/dchu917/ctx/main/scripts/install.sh | bash 安装固定版本到 ~/.contextfun，包含 ctx 二进制、Python 包、默认数据库及自包含 Claude/Codex 技能。 ### 先用 skills.sh 安装引导技能 bash npx skills add https://github.com/dchu917/ctx --skill ctx -y -g 先安装 ctx 引导技能，而非直接装 CLI。之后捆绑的 skills/ctx/scripts/ctx.sh 可在首次使用时执行 ctx install 或自动装全局 CLI 到 ~/.contextfun。 ### 无手动克隆的代理 shell 引导 全局 shell 引导： bash source <(curl -fsSL https://raw.githubusercontent.com/dchu917/ctx/main/scripts/agent_bootstrap.sh) 项目本地 shell 引导： bash source <(curl -fsSL https://raw.githubusercontent.com/dchu917/ctx/main/scripts/agent_setup_local_ctx.sh) 适用于 Claude Code 或 Codex 终端。 ### 克隆后手动高级配置 仓库版 ctx shim： bash bash scripts/install_shims.sh 仅链接技能： bash bash scripts/install_skills.sh 如需自定义技能目录： bash CODEX_SKILLS_DIR=/custom/codex/skills \ CLAUDE_SKILLS_DIR=/custom/claude/skills \ bash scripts/install_skills.sh ## 文档 - 安装与卸载 - 使用方法 - 架构说明 - 集成指南 - 仓库结构 - 维护与发布 - 文档索引 ## 整理已保存记忆 使用 ctx curate <工作流> 审查将用于未来加载的条目： bash ctx curate my-stream 终端界面操作： - j / k 或方向键上下移动 - Enter 切换大预览 - p 固定条目，即使压缩模式也加载 - x 排除条目，不再加载但仍保存且可搜索 - a 恢复默认加载行为 - d 标记待删除，y 确认 - q 退出 说明： - 仅修改 ctx 记忆，不会动原始 Claude/Codex 聊天记录。 - 非交互 shell 可用 ctx web --open 在浏览器详情页管理。 - ctx delete --interactive <工作流> 也会打开此界面。 - 详见 docs/usage.md 与 docs/architecture.md。 ## 清空工作流 使用 ctx clear 一次性删除工作流及其关联会话与条目： bash ctx clear --this-repo --yes ctx clear --all --yes 说明： - --this-repo 仅删除与当前仓库关联的工作流。 - --all 删除当前 ctx 数据库中所有工作流。 - 必须带 --yes 才执行删除；否则仅打印待删除内容并退出。 - 仅清除 ctx 管理的记忆、附件及指针，不会删除原始 Claude/Codex 聊天文件。 ## 安全 ctx 是上下文层，非沙箱。威胁模型见 SECURITY.md，运维注意事项见 docs/maintenance.md。 ## 常见问题 需要 API 密钥吗？ - 不需要，全部本地。 多仓库能共享同一上下文数据库吗？ - 可以。将 ctx_DB 设为共享路径如 ~/.contextfun/context.db。 删除 ctx 会话会删原 Claude/Codex 聊天吗？ - 不会，仅删内部 ctx 会话及附件。 ## 许可证 MIT，详见 LICENSE。