@tarunspandit/codexflow 0.29.0

package/README_ZH.md

@@ -0,0 +1,461 @@
+<p align="center">
+  <a href="https://tarunspandit.github.io/codexflow/zh.html"><img src="docs/og.png" width="900" alt="CodexFlow — 一条命令，所有项目，任何对话"></a>
+</p>
+
+<h1 align="center">CodexFlow</h1>
+
+<p align="center">
+  让 ChatGPT Web 看见你的本地仓库，并像本地代码代理一样工作。
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@tarunspandit/codexflow"><img alt="npm" src="https://img.shields.io/npm/v/@tarunspandit/codexflow?style=flat-square"></a>
+  <a href="https://github.com/tarunspandit/codexflow/actions"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/tarunspandit/codexflow/ci.yml?branch=main&style=flat-square"></a>
+  <a href="https://github.com/tarunspandit/codexflow/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/tarunspandit/codexflow?style=flat-square"></a>
+</p>
+
+CodexFlow 是独立开源项目，与 OpenAI 没有隶属、合作、赞助或官方背书关系。文中提到 Codex、ChatGPT 和 OpenAI 仅用于说明兼容性；相关名称和商标归其各自权利人所有。
+
+<p align="center">
+  <a href="README.md">English</a>
+  ·
+  <a href="https://github.com/tarunspandit/codexflow">GitHub 点星</a>
+  ·
+  <a href="https://www.npmjs.com/package/@tarunspandit/codexflow">npm</a>
+  ·
+  <a href="DOMAIN_SETUP.md">稳定 URL 指南</a>
+  ·
+  <a href="FAQ_ZH.md">中文 FAQ</a>
+  ·
+  <a href="SECURITY.md">安全说明</a>
+</p>
+
+## 安装
+
+codexflow 需要 Node.js 20+，以及能使用 Apps / Developer Mode 的 ChatGPT 账号。OpenAI 当前文档列出的 web 端 Developer Mode 账号范围包括 Pro、Plus、Business、Enterprise 和 Education。
+
+先安装 CLI：
+
+```bash
+npm install -g @tarunspandit/codexflow
+```
+
+GitHub `main` 文档可能早于 npm 发布；用 `npm install -g @tarunspandit/codexflow` 前请看 npm badge/version，未发布的 `main` 行为请用下面的 source checkout 方式。
+
+然后在任何目录运行唯一的启动命令：
+
+```bash
+codexflow
+```
+
+codexflow 会从本机 Codex metadata 自动发现所有项目，启动 broker 和 Cloudflare tunnel，并复制 ChatGPT Server URL。先到 `Settings -> Security and login` 打开 Developer mode，再到 `Settings -> Plugins` 创建连接，粘贴这个 URL，并选择 `Authentication: No Authentication / None`。
+
+codexflow 把 ChatGPT Developer Mode 变成本地仓库的 MCP 代码代理。ChatGPT 可以读取文件、搜索代码、查看 git 状态、写入或精确编辑文件，并运行安全范围内的验证命令。
+
+codexflow 不是速率限制绕过工具。它不会绕过、提升、合并、转售或修改 ChatGPT、Codex、OpenAI 或第三方模型的限制。它只是通过官方 Developer Mode / MCP App 路径，把你自己的 ChatGPT 会话连接到你自己的本地仓库。
+
+如果 Codex 当前工作流暂时不可用，而你的 ChatGPT 页面仍然可用，CodexFlow 可以让你继续在同一个本地仓库上工作。反过来也一样：ChatGPT 负责高上下文规划，Codex、OpenCode、Pi 或其他本地执行器负责终端里的实际执行。
+
+## 适合谁
+
+codexflow 适合已经有 ChatGPT Apps / Developer Mode 权限并希望做本地开发的人：
+
+- 想让 ChatGPT Web 直接读取本地代码，而不是反复复制文件片段。
+- 想把 `AGENTS.md`、`.ai-bridge`、git diff、源码文件这些 Codex 风格上下文给 ChatGPT。
+- 想在 ChatGPT 里完成规划、审查、改小文件、跑安全验证。
+- 想在某些模型不能调用工具时，导出一个持久上下文包给它做规划。
+- 想把 ChatGPT 的计划交给 Codex、OpenCode、Pi 或自定义本地代理执行。
+
+当前测试显示，ChatGPT Free / Go 账号不暴露 CodexFlow 需要的 Apps / Developer Mode 创建流程。请使用 ChatGPT 中能看到 Apps / Developer Mode 的账号层级。
+
+## 它能做什么
+
+```text
+ChatGPT Web 可以看到：
+  AGENTS.md
+  .ai-bridge 计划、状态和执行记录
+  git status
+  show_changes 审查摘要和可选 diff
+  文件树、搜索结果、指定源码文件
+
+ChatGPT Web 可以操作：
+  read    读取文件
+  search  搜索代码
+  write   在工作区内写文件
+  edit    精确替换文本
+  bash    运行安全验证命令
+  show_changes 查看当前改动摘要
+
+本地执行器仍然有价值：
+  Codex / OpenCode / Pi 执行计划
+  终端重任务留在本地
+  ChatGPT 回看执行结果和 diff
+```
+
+默认 `CODEXFLOW_TOOL_MODE=standard`，只暴露常用编码循环、`codexflow_self_test`、`show_changes`、上下文导出和 handoff。演示时可以用 `--tool-mode minimal`，需要完整兼容工具时用 `--tool-mode full`。
+
+默认工具数量较少是故意的：ChatGPT 面对少量高信号工具时更稳定。workspace open 默认不做 skill discovery；需要 repo-local skills 时传 `include_skills=true`，需要 user/plugin skills 时再加 `include_global_skills=true`。然后用 `load_skill` 按名称、source 和显示出的 path 加载需要的 `SKILL.md`；如果仍有重名匹配，CodexFlow 会报歧义错误，不会随便选一个，也不会把几十个 skill 变成单独 action。
+
+codexflow 默认给 ChatGPT 暴露纯 MCP 工具描述，不附带 widget/card metadata。需要紧凑 v9 卡片时用 `CODEXFLOW_TOOL_CARDS=1` 启动；server config、自测、workspace 摘要、读写 diff、bash 验证、git/tree/search/context 和 handoff/export 都有结构化视图。git、skills、tree、terminal 输出、context 和 raw diff 会折叠或截断，避免在聊天里刷出大段原始数据。`CODEXFLOW_WIDGET_DOMAIN` 用于设置 ChatGPT widget iframe 的专用 HTTPS origin，正式提交 app 前应换成你控制的独立域名。
+
+## 其他启动方式
+
+不想全局安装时，也可以用：
+
+```bash
+npx codexflow@latest --root /absolute/path/to/your/repo
+```
+
+但普通用户更推荐全局安装，这样唯一的启动命令就是 `codexflow`。
+
+## ChatGPT 中的 App 设置
+
+先在 ChatGPT 打开 Developer Mode：
+
+```text
+ChatGPT Settings
+-> Security and login
+-> Developer mode: on
+-> Enforce CSP in developer mode: on
+
+ChatGPT Settings
+-> Plugins
+-> Create
+```
+
+保留 CSP 开启。CodexFlow 的卡片和小组件就是按 CSP 开启的路径设计的，不需要远程脚本、外部字体、iframe 或第三方图片。
+
+在创建 Plugin 页面填写：
+
+```text
+Name: CodexFlow
+Description: Local workspace bridge for ChatGPT coding
+Connection: Server URL
+Server URL: 粘贴 CodexFlow 自动复制的 URL
+Authentication: No Authentication / None
+```
+
+复制的 Server URL 已经包含私有 `codexflow_token`。不要单独粘贴 token，除非你的 ChatGPT UI 明确支持自定义 header。
+
+保持终端里的 CodexFlow 进程运行。你停止它之后，ChatGPT 就无法继续连接本地仓库。Cloudflare quick tunnel 的 URL 也会失效。
+
+## 三种主要模式
+
+### 1. Normal coding
+
+默认模式。ChatGPT 可以在工作区内读取、搜索、写入、精确编辑文件，并运行安全验证命令。
+
+```bash
+codexflow
+```
+
+适合小改动、文档更新、定位 bug、查看 diff、跑 lint/test/build。
+
+如果你正在另一个 Codex 会话里工作，不希望 ChatGPT 触发任何 shell 命令，用：
+
+```bash
+codexflow --no-bash
+```
+
+如果想保留 bash，但要求 ChatGPT 明确命中你启动的这个 CodexFlow 终端会话标签，用：
+
+```bash
+codexflow --bash-session main --require-bash-session
+```
+
+开启后，`bash` 工具调用必须带上 `session_id: "main"` 才会执行。
+
+### 2. Handoff
+
+规划模式。ChatGPT 不直接写源码，只写入：
+
+```text
+.ai-bridge/current-plan.md
+```
+
+然后你在本地终端决定是否执行：
+
+```bash
+codexflow execute-handoff --agent opencode --model provider/model --dry-run
+codexflow execute-handoff --agent opencode --model provider/model
+```
+
+也可以启动监听器，让本地终端在计划变更后执行：
+
+```bash
+codexflow --mode handoff
+codexflow --mode handoff --no-bash
+codexflow watch-handoff --agent opencode --model provider/model --yes
+```
+
+执行结果会写回：
+
+```text
+.ai-bridge/agent-status.md
+.ai-bridge/implementation-diff.patch
+.ai-bridge/execution-log.jsonl
+```
+
+然后让 ChatGPT 通过 `read_handoff` 或 `codex_context` 审查结果。
+
+### 3. Pro context fallback
+
+有些 ChatGPT 模型或产品界面不能直接调用 Developer Mode Apps、连接器或 MCP 工具。即使同一个符合条件的账号可以创建 CodexFlow app，某个具体模型界面仍然可能没有工具调用能力。
+
+这时不要强行让它调用工具。先导出一个持久上下文包：
+
+```bash
+codexflow pro-bundle --root /absolute/path/to/your/repo --copy
+```
+
+它会写入：
+
+```text
+.ai-bridge/pro-context.md
+```
+
+把这个上下文粘贴给不能调用工具的模型，让它产出窄范围实现计划。然后保存计划并应用：
+
+```bash
+codexflow pro-apply --root /absolute/path/to/your/repo --file plan.md
+```
+
+这会写入 `.ai-bridge/current-plan.md`，再交给 Codex、OpenCode、Pi 或自定义本地代理执行。
+
+如果你的 ChatGPT 账号已经在 Web 产品里提供 GPT-5.5 或更强模型，并且该模型界面可以调用 Developer Mode Apps，CodexFlow 可以让它通过 MCP 使用本地仓库工具。CodexFlow 不提供、不代理、不转售、也不解锁模型。
+
+## 稳定 URL 怎么选
+
+ChatGPT App 需要一个可访问的 Server URL。你有三个常用选择：
+
+```text
+Cloudflare quick tunnel   最快演示路径。每次重启 URL 都变。
+ngrok free dev domain     推荐给大多数用户。免费账号给一个稳定 dev domain。
+Cloudflare named tunnel   适合已有自定义域名的用户。
+```
+
+### Cloudflare quick tunnel
+
+最适合录 demo 或临时试用：
+
+```bash
+codexflow
+```
+
+缺点很明确：quick tunnel 的 URL 每次重启都会变。如果你把 quick URL 放进 ChatGPT App，下一次启动时需要重新编辑 ChatGPT App 的 Server URL。
+
+### ngrok free dev domain
+
+推荐给大多数用户。创建一个免费 ngrok 账号，在 ngrok Dashboard 的 Universal Gateway -> Domains 找到你的 dev domain，比如：
+
+```text
+your-name.ngrok-free.dev
+```
+
+一次性认证 ngrok：
+
+```bash
+ngrok config add-authtoken YOUR_NGROK_TOKEN
+```
+
+保存到 CodexFlow：
+
+```bash
+codexflow settings set --tunnel ngrok --hostname your-name.ngrok-free.dev
+```
+
+以后启动：
+
+```bash
+codexflow
+```
+
+ChatGPT 里的 Server URL 可以保持不变。
+
+### Cloudflare named tunnel
+
+如果你有自己的域名，可以用 Cloudflare named tunnel：
+
+```bash
+cloudflared tunnel login
+cloudflared tunnel create CodexFlow
+cloudflared tunnel route dns CodexFlow codexflow.example.com
+```
+
+之后日常启动：
+
+```bash
+codexflow stable --hostname codexflow.example.com --tunnel-name codexflow
+```
+
+更多域名细节见 [DOMAIN_SETUP.md](DOMAIN_SETUP.md)。
+
+## Codex 风格上下文
+
+codexflow 不读取 Codex 的隐藏运行时记忆。它给 ChatGPT 的是显式工作区上下文：
+
+```text
+open_current_workspace  当前 root、安全模式、AGENTS 状态、git 状态
+codex_context           AGENTS 链、.ai-bridge 文件、可选 git status/diff
+read_handoff            只读 .ai-bridge 文件
+workspace_snapshot      更大的项目快照和 handoff 上下文
+```
+
+`codex_context` 会读取从仓库根目录到目标路径上的指令文件：
+
+```text
+AGENTS.override.md
+AGENTS.md
+agents.md
+.agents.md
+```
+
+并加入：
+
+```text
+.ai-bridge/current-plan.md
+.ai-bridge/agent-status.md
+.ai-bridge/implementation-diff.patch
+.ai-bridge/codex-status.md
+.ai-bridge/decisions.md
+.ai-bridge/open-questions.md
+.ai-bridge/execution-log.jsonl
+git status
+可选 git diff
+```
+
+推荐流程：
+
+```text
+先调用 server_config 和 codexflow_self_test
+如果 self-test 失败，先停下来报告失败项
+先调用 open_current_workspace，include_tree=false
+再调用 codex_context，target_path 指向要改的文件，include_diff=false
+然后只读取当前任务需要的文件
+```
+
+这样 ChatGPT 会更接近 Codex 的指令模型，同时不会依赖隐藏状态或大范围重复扫描。
+
+## 安全边界
+
+codexflow 是本地开发桥，不是操作系统级沙箱。
+
+默认安全行为：
+
+- 公网 tunnel 默认需要私有 CodexFlow token。
+- 写入限制在配置的工作区 root 内。
+- 常见敏感路径会被拒绝：`.env`、私钥、`.git`、`node_modules`、生成目录、缓存目录。
+- symlink 逃逸会被阻止。
+- safe bash 只允许常见检查、搜索、git、lint、test、typecheck、build 等命令。
+- `codexflow --no-bash` 会完全关闭 ChatGPT 可调用的 bash 工具。
+- `execute-handoff` 和 `watch-handoff` 是本地 CLI 命令，不是远程 MCP 工具。
+
+只有在你信任当前仓库和命令时，才考虑更宽的权限，例如 full bash、自定义执行器、额外 allow root。
+
+### Codex 会话边界
+
+codexflow 的 MCP transport session id 不代表 Codex 聊天。CodexFlow 不会启动或恢复 Codex CLI；ChatGPT 提供模型，CodexFlow 提供本地文件、git、terminal、仓库规则和 skill 工具。
+
+`bash` 工具属于你启动的 CodexFlow 本地服务器进程，并在当前聊天选中的项目目录下运行。并行任务可以通过同一个 broker/tunnel 在不同聊天中选择不同项目；这不是“远程控制当前 Codex 会话”。
+
+如果要减少误触发，可以给这个本地 CodexFlow 进程设置 bash session guard：
+
+```bash
+codexflow --bash-session main --require-bash-session
+```
+
+这不是 Codex App 聊天会话 id，而是 CodexFlow 本地 bash 工具的显式匹配标签。
+
+bash 结果默认使用紧凑 transcript，避免 ChatGPT 对话里突然铺开大段 stdout/stderr。完整 stdout/stderr 仍在结构化工具数据里，CodexFlow 卡片里的输出预览默认折叠。需要旧行为时可以显式打开：
+
+```bash
+codexflow --bash-transcript full
+```
+
+codexflow 也可以在 full tools 下显式开启只读的本地 Codex 会话列表：
+
+```bash
+codexflow --tool-mode full --codex-sessions metadata
+codexflow --tool-mode full --codex-sessions read
+```
+
+`metadata` 会增加 `codex_sessions` 工具，从本地历史列出 session；`read` 还会增加有限长度的 transcript 读取。它们只读取历史，不执行 Codex。
+
+一个 broker/tunnel 可以同时服务多个网页聊天：
+
+```bash
+codexflow --tool-mode full --root /path/to/default-repo --allow-root /path/to/projects
+```
+
+新聊天调用 `list_projects` 后会显示项目选择器。目录来源包括默认项目、allowed roots 下发现的项目，以及本机 Codex metadata 中最近使用且仍在 allowed roots 内的目录。`select_project` 会把当前 ChatGPT MCP 会话绑定到所选目录；之后不传 `workspace_id` 的文件、git、搜索、编辑和 terminal 调用都会自动路由到该项目。其他网页聊天拥有独立绑定。选择项目时也会发布 repo 指令、workspace/user/plugin skills 和已配置 MCP server 名称。
+
+如果 Codex 历史不在默认位置，可以用 `--codex-dir <dir>`。
+
+如果只想让 ChatGPT 规划、由你本地决定是否执行：
+
+```bash
+codexflow --mode handoff --no-bash
+```
+
+## 常用命令
+
+```bash
+codexflow
+codexflow
+codexflow --non-interactive
+codexflow status
+codexflow status --json
+codexflow doctor
+codexflow settings
+codexflow settings list
+codexflow settings set --tunnel ngrok --hostname your-name.ngrok-free.dev
+codexflow settings delete --yes
+codexflow pro-bundle --copy
+codexflow execute-handoff --agent opencode --model provider/model --dry-run
+codexflow watch-handoff --agent opencode --model provider/model --yes
+```
+
+终端控制键：
+
+```text
+Enter  打开 ChatGPT connector 设置
+c      再次复制 Server URL
+o      打开本地 admin dashboard
+h      显示帮助
+q      停止 CodexFlow
+```
+
+在脚本、CI 或没有交互式终端的环境中，使用 `--non-interactive`。连接器会继续运行，直到收到 SIGINT/SIGTERM；`codexflow status --json` 可用于自动化检查。
+
+本地 admin dashboard 是带 token 保护的 setup/settings 页面。它会显示当前 workspace、local MCP endpoint、安全模式、安装/启动命令、ChatGPT 连接步骤、saved profile 设置和 allowed roots。
+
+页面也提供 GitHub、npm、docs 链接和高级重启命令。普通用户不需要 profile 或 setup；可选高级设置仍能修改 tunnel、hostname、port、bash、write/tool mode 和 widget origin，重启 `codexflow` 后生效。
+
+浏览器 admin 页面只负责 setup/settings/status 和 MCP endpoint；不能切换 ChatGPT 账号，不能直接保存原始 Cloudflare tunnel token，也不能把 CodexFlow 作为后台服务开关。Cloudflare dashboard-managed tunnel 请把 token 放在本地文件里，再填写 Cloudflare token file。
+
+## FAQ
+
+中文常见问题见 [FAQ_ZH.md](FAQ_ZH.md)。
+
+核心结论：
+
+- 需要能访问 Apps / Developer Mode 的 ChatGPT 账号。
+- Free / Go 在当前测试中不支持这个 App 创建流程。
+- CodexFlow 不绕过任何速率限制。
+- 某些 Pro / planning 模型界面不能直接连接 MCP 工具，使用 `pro-bundle` 作为上下文回退。
+- quick tunnel 每次重启 URL 会变。
+- 想每天同一个 URL，用 ngrok free dev domain 或 Cloudflare named tunnel。
+
+## 开源与贡献
+
+项目地址：[github.com/tarunspandit/codexflow](https://github.com/tarunspandit/codexflow)
+
+欢迎提 issue、补文档、补平台兼容性、补测试。提交 PR 前请至少运行：
+
+```bash
+npm run build
+npm run smoke
+npm audit --omit=dev
+```
+
+如果 CodexFlow 对你有用，请在 GitHub 点星。这样其他使用 ChatGPT、Codex、OpenCode、Pi 和 MCP 的开发者更容易找到它。

package/SECURITY.md

@@ -0,0 +1,145 @@
+# Security Policy
+
+codexflow exposes a local workspace to an MCP client. Treat it like a developer tool with access to your source tree, not like a hosted SaaS app.
+
+## Supported Version
+
+Security fixes target the latest published version only until the project reaches `1.0.0`.
+
+Feature-specific notes follow GitHub `main`; npm users should check the published version before relying on a new command.
+
+## Reporting
+
+Please report security issues privately before opening a public issue. If the repository has GitHub private vulnerability reporting enabled, use that. Otherwise contact the maintainer listed by the project owner.
+
+Do not include secrets, private repository contents, tunnel tokens, or `.env` values in reports.
+
+## Terms Boundary
+
+codexflow is not designed to bypass, avoid, pool, resell, or modify ChatGPT, Codex, OpenAI, or third-party model limits. Do not market, deploy, or configure it that way.
+
+Each user should connect their own ChatGPT account, use only product surfaces available to that account, and follow the limits, safety rules, and terms for ChatGPT, Codex, OpenAI, and any third-party model provider they connect.
+
+## Threat Model
+
+codexflow can expose:
+
+- file metadata and selected file contents from allowed workspaces
+- git status and diffs
+- `.ai-bridge` planning files
+- optional shell command execution through the `bash` tool, hidden when bash mode is off
+- optional write/edit/apply_patch capability depending on `CODEXFLOW_WRITE_MODE`, advertised only in workspace write mode
+- optional local handoff execution through `codexflow execute-handoff`, run from the user's terminal only
+- optional local execute/review looping through `codexflow loop-handoff`, run from the user's terminal only with a user-provided reviewer command and iteration limit
+
+## Failure Model
+
+Review changes against these failure modes before release:
+
+| Failure mode | Expected control |
+| --- | --- |
+| Public tunnel reachable without a secret | Public/non-loopback HTTP fails closed unless a CodexFlow token is configured. |
+| Raw CodexFlow or Cloudflare token appears in UI, logs, docs, or package output | Tokens are redacted in profile/status output and tunnel tokens use local files for persistence. |
+| ChatGPT can edit outside the intended repo | Allowed roots are explicit; path resolution rejects escapes, blocked globs, and symlink traversal. |
+| ChatGPT can run arbitrary shell by default | Bash defaults to safe mode, can be disabled, and full mode is a trusted-local-only choice. Safe mode can still run repo package scripts, so use `--no-bash` for untrusted repos. |
+| Handoff mode still exposes generic writes | Handoff/pro modes do not advertise generic `write`/`edit`/`apply_patch`; bounded handoff tools write `.ai-bridge` files only. |
+| Local Codex history is treated as ChatGPT memory | Codex session access is opt-in metadata/read mode and never attaches to a live Codex app session. |
+| Browser admin mutates live runtime unexpectedly | Admin profile changes apply on restart; active runtime policy stays stable for the current session. |
+| Remote MCP tool runs Codex/OpenCode/Pi directly | Agent execution remains a user-started CLI/watch process on the local machine. |
+| Autonomous loop drives ChatGPT Web or bypasses approvals | `loop-handoff` only runs local terminal commands over `.ai-bridge` files; it does not resume browser sessions, approve prompts, or expose a remote MCP executor. |
+| Reviewer masks a failed external command | `loop-handoff` requires explicit reviewer verdict assignments and rejects reviewer `PASS` after failed executor, test, or reviewer commands unless the user opts into the supported executor/test override behavior. |
+
+The main risks are:
+
+- connecting an untrusted MCP client
+- exposing the server through a public tunnel without auth
+- running with `CODEXFLOW_BASH_MODE=full`
+- running with `CODEXFLOW_WRITE_MODE=workspace` on an important repo
+- executing an untrusted `.ai-bridge/current-plan.md` or custom `execute-handoff --command`
+- running `loop-handoff` with an untrusted reviewer command or without a small `--max-iters`
+- adding overly broad allowed roots
+- leaking a `codexflow_token` or Cloudflare tunnel token
+- trusting a downloaded `cloudflared` binary without understanding where it came from
+
+## Safer Defaults
+
+Default daily mode:
+
+```bash
+codexflow \
+  --root /path/to/repo \
+  --bash safe \
+  --tunnel cloudflare
+```
+
+Safer planning-only mode:
+
+```bash
+codexflow \
+  --root /path/to/repo \
+  --mode handoff \
+  --bash safe \
+  --tunnel cloudflare
+```
+
+For stable public hostnames, keep the CodexFlow auth token stable but private:
+
+```bash
+codexflow \
+  --root /path/to/repo \
+  --tunnel cloudflare-named \
+  --hostname codexflow.example.com \
+  --tunnel-name codexflow \
+  --token <long-random-token> \
+  --bash safe
+```
+
+## Hard Rules
+
+- Do not run public tunnels with `--no-auth`.
+- Public tunnel mode and non-loopback binds fail closed if `CODEXFLOW_HTTP_TOKEN` is missing.
+- Do not commit printed connector URLs that include `codexflow_token`.
+- Do not commit Cloudflare tunnel tokens.
+- Do not paste raw Cloudflare tunnel tokens into browser pages or screenshots. Use `--cloudflare-token-file` or the local page's Cloudflare token file field instead.
+- Use `--mode handoff` for planning workflows where ChatGPT should not edit source files. Handoff mode does not advertise generic `write`/`edit` tools.
+- Preview local handoff execution with `codexflow execute-handoff --dry-run` before running an unfamiliar adapter or custom command.
+- Preview autonomous local loops with `codexflow loop-handoff --dry-run`, keep `--max-iters` small, and prefer `--require-human-confirmation` until you trust the reviewer command.
+- Keep `execute-handoff` local. Do not wrap it in a remote MCP tool unless you add a stronger approval and sandbox story.
+- Keep `loop-handoff` local. Do not use it to automate ChatGPT Web, Codex approvals, account access, third-party Pro sites, quota limits, or product safety prompts.
+- Use default agent mode only with trusted ChatGPT sessions and repo-specific roots.
+- Use `--no-bash` when ChatGPT should never trigger shell commands in the workspace.
+- Use `--bash-session <id> --require-bash-session` when bash should be enabled only for calls that explicitly target this local CodexFlow terminal label.
+- Keep Codex session history access off unless needed. `--codex-sessions metadata` only lists local Codex JSONL metadata; `--codex-sessions read` allows bounded transcript reads.
+- Keep `CODEXFLOW_CONTEXT_DIR` as a workspace-relative hidden directory such as `.ai-bridge`; CodexFlow rejects source, build, dependency, credential, and absolute context directories.
+- Use `--bash full` only for trusted local repos.
+- Do not treat MCP session ids or bash session labels as Codex conversation ids. CodexFlow does not execute inside a Codex app session.
+- Prefer a repo-specific `--root` instead of `--allow-home`.
+- Use `--no-install-cloudflared --cloudflared <path>` if your organization requires a managed Cloudflare Tunnel binary.
+
+## Cloudflare Binary Install
+
+For the one-command public tunnel flow, CodexFlow can download the official Cloudflare `cloudflared` release into `~/.codexflow/bin` on supported macOS, Windows, and Linux systems. It does not install a system service, does not use sudo/admin rights, and does not modify shell startup files.
+
+Resolution order:
+
+```text
+1. explicit --cloudflared path or CLOUDFLARED_BIN
+2. cloudflared already available in PATH
+3. ~/.codexflow/bin/cloudflared or cloudflared.exe
+4. download official Cloudflare latest release unless --no-install-cloudflared is set
+```
+
+Use `--install-cloudflared` to refresh the local binary. Use `--no-install-cloudflared` to disable downloads.
+
+## Built-In Guards
+
+codexflow blocks common sensitive paths by default:
+
+- `.env` and `.env.*`
+- `.git` internals
+- `node_modules`
+- common private key names
+- build/cache folders such as `dist`, `build`, `.next`, `coverage`, `.cache`
+- symlinks that resolve outside the workspace or into blocked paths
+
+These guards reduce risk. They are not an OS sandbox.

package/config.example.env

@@ -0,0 +1,31 @@
+# Copy to .envrc or source manually before running npm run start:http.
+CODEXFLOW_ROOT=/absolute/path/to/your/repo
+# Project-library roots shown by the ChatGPT project picker. Separate multiple paths with the OS path delimiter.
+CODEXFLOW_ALLOWED_ROOTS=/absolute/path/to/projects
+CODEXFLOW_HOST=127.0.0.1
+CODEXFLOW_PORT=8787
+CODEXFLOW_BASH_MODE=safe
+# Optional local bash session guard. If required, bash tool calls must include the matching session_id.
+# CODEXFLOW_BASH_SESSION_ID=main
+# CODEXFLOW_REQUIRE_BASH_SESSION=1
+CODEXFLOW_WRITE_MODE=handoff
+CODEXFLOW_TOOL_MODE=standard
+# Dedicated HTTPS origin for ChatGPT widget iframes. Required for app submission.
+CODEXFLOW_WIDGET_DOMAIN=https://tarunspandit.github.io
+
+# Disabled by default so ChatGPT receives plain MCP tool descriptors.
+# Set to 1 only if you want CodexFlow's custom ChatGPT cards.
+CODEXFLOW_TOOL_CARDS=0
+CODEXFLOW_HTTP_TOKEN=replace-with-a-long-random-token
+# Require a token even for loopback binds. Non-loopback and tunnel mode require one unless explicitly overridden.
+# CODEXFLOW_REQUIRE_HTTP_TOKEN=1
+# CODEXFLOW_ALLOW_NO_HTTP_TOKEN=1
+CODEXFLOW_CONTEXT_DIR=.ai-bridge
+# Optional stable public URL mode. Quick tunnels do not keep the same hostname.
+# CODEXFLOW_TUNNEL=cloudflare-named
+# CODEXFLOW_PUBLIC_HOSTNAME=codexflow.example.com
+# CLOUDFLARE_TUNNEL_NAME=codexflow
+# Or use a dashboard-managed tunnel token:
+# CLOUDFLARE_TUNNEL_TOKEN_FILE=/Users/you/.codexflow/cloudflare-tunnel-token
+# Optional comma-separated extra block list:
+# CODEXFLOW_BLOCKED_GLOBS=**/secrets/**,**/*.sqlite,**/*.db

package/dist/analysis/cache.js

@@ -0,0 +1,27 @@
+const MAX_CACHE_ENTRIES = 8;
+const cache = new Map();
+export function getCachedWorkspaceAnalysis(key) {
+    const value = cache.get(key);
+    if (!value)
+        return undefined;
+    cache.delete(key);
+    cache.set(key, value);
+    return value;
+}
+export function setCachedWorkspaceAnalysis(key, value) {
+    cache.delete(key);
+    cache.set(key, value);
+    while (cache.size > MAX_CACHE_ENTRIES) {
+        const oldest = cache.keys().next().value;
+        if (!oldest)
+            break;
+        cache.delete(oldest);
+    }
+}
+export function invalidateWorkspaceAnalysis(workspaceId) {
+    for (const key of cache.keys()) {
+        if (key.startsWith(`${workspaceId}:`))
+            cache.delete(key);
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/analysis/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/analysis/cache.ts"],"names":[],"mappings":"AAEA,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAC5B,MAAM,KAAK,GAAG,IAAI,GAAG,EAA6B,CAAC;AAEnD,MAAM,UAAU,0BAA0B,CAAC,GAAW;IACpD,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAClB,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACtB,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,0BAA0B,CAAC,GAAW,EAAE,KAAwB;IAC9E,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAClB,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACtB,OAAO,KAAK,CAAC,IAAI,GAAG,iBAAiB,EAAE,CAAC;QACtC,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAA2B,CAAC;QAC/D,IAAI,CAAC,MAAM;YAAE,MAAM;QACnB,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACvB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,WAAmB;IAC7D,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAC/B,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,WAAW,GAAG,CAAC;YAAE,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3D,CAAC;AACH,CAAC"}