@tarunspandit/codexflow 0.29.0

package/AGENTS.example.md

@@ -0,0 +1,18 @@
+# AGENTS.md example
+
+This repo is connected through CodexFlow.
+
+Rules for ChatGPT or another planning model:
+
+- Prefer planning and review over direct implementation.
+- Use handoff_to_codex to write .ai-bridge/current-plan.md.
+- Do not edit source files unless the user explicitly asks.
+- Always inspect git_status and git_diff before reviewing.
+- Respect .ai-bridge/decisions.md.
+
+Rules for Codex:
+
+- Read .ai-bridge/current-plan.md before changing code.
+- Execute in small steps.
+- Update .ai-bridge/codex-status.md after meaningful changes.
+- Include tests run and results.

package/CHANGELOG.md

@@ -0,0 +1,311 @@
+# Changelog
+
+## Unreleased
+
+## 0.29.0 (2026-07-13)
+
+- Launched the redesigned English and Chinese CodexFlow website, social card, public npm identity, and renamed GitHub repository.
+- Added `codexflow status` with human-readable and `--json` runtime/process/health reporting, plus `--non-interactive` / `--no-control-panel` for script and CI launches.
+- Added a synchronized project picker and per-ChatGPT-session project binding, allowing one broker and tunnel to route concurrent web coding chats to different local repositories without invoking the Codex CLI.
+- Project selection now advertises repository instructions, workspace/user/plugin skills, locally available plugin manifests, and configured MCP server names.
+- Renamed the product, npm package, executable, MCP identity, environment namespace, local state directory, widgets, and documentation from CodexPro/codeXchat to CodexFlow/`codexflow`.
+- Removed first-run setup from the normal path: bare `codexflow` discovers project directories from local Codex metadata, chooses the most recent project as the default, starts the broker and quick tunnel, and copies the ChatGPT connection URL.
+- Bumped the interactive tool resource to `ui://widget/codexflow-tool-card-v10.html` while retaining v9/v8 compatibility aliases, preventing stale ChatGPT widget caches from hiding the project picker.
+
+## 0.29.0-beta.1 (npm beta, 2026-07-11)
+
+- Added bounded multi-language repository analysis, grouped search results, change-impact and test recommendations, `codexflow inspect` / `codexflow review` CLI commands, and compact opt-in tool cards.
+- Added `codexflow connection-test`, a read-only connector profile with no bash or tool cards, plus request-arrival logging and current ChatGPT Plugins troubleshooting.
+- Added Tailscale Funnel as a saved tunnel/profile option, including `codexflow tailscale --hostname ...`, launcher support, admin profile support, and settings smoke coverage.
+- Added proxy-aware Cloudflare quick tunnels: when proxy env vars are set, CodexFlow requests quick-tunnel credentials through `curl --proxy`, runs `cloudflared` with a temporary credentials file, ignores Cloudflare API URLs, and cleans the credentials file after shutdown.
+- Hardened Codex handoff execution on Windows by resolving spawnable Codex shims, asking Codex to read the plan file instead of argv-passing the whole plan, and recording git status in handoff artifacts.
+- Added concise connector-creation troubleshooting to the English and Chinese FAQs.
+- Bounded browser-facing tool-card structured payloads and binary-file text checks so CodexFlow emits less data without reducing normal tool-result or binary-detection quality.
+- Allowed targeted line-range reads and search matches in text files slightly above `maxReadBytes`, while keeping full-file reads and very large scans bounded.
+- Replaced the overlong README with a shorter install, tunnel, safety, RAM-boundary, and development guide.
+- Added a guarded `apply_patch` MCP tool for unified-diff edits inside workspace write mode, with blocked-path and secret-content checks before patches are applied.
+- Added last-shown review checkpoints to `show_changes`, so repeated unchanged reviews collapse while new workspace changes still produce a fresh diff.
+- Fixed checkpoint-hit `show_changes` responses so repeated unchanged reviews report zero new diff stats instead of carrying stale addition/deletion counts.
+- Scoped `apply_patch` result diffs to the applied patch, so unrelated dirty tracked files are not folded into the patch card.
+- Hardened safe bash filtering, path canonicalization, binary-file checks, ripgrep truncation reporting, and supertool argument validation around edge-case bypasses found by stress testing.
+- Redacted child tunnel process output before logging or surfacing startup failures so Cloudflare `TUNNEL_TOKEN` values cannot leak from failed named-tunnel launches.
+- Kept `codex_sessions` metadata mode from returning transcript-tail summaries, skipped unreadable stale history files, and accepted source paths under symlink-resolved Codex history roots.
+- Hardened search, context export, path blocking, skill loading, and change summaries around hidden files, colon-containing paths, `.env` descendants, large-file limits, user skills, and diff stats.
+- Blocked raw newline and carriage-return command separators in safe bash mode before whitespace normalization, including through the stable `codexflow` supertool wrapper.
+- Corrected docs to describe Developer Mode account eligibility as broader than Plus/Pro while keeping the model/tool-surface limitation explicit.
+
+## 0.28.6 (main, pending npm latest)
+
+- Added the stable `codexflow` supertool wrapper for advanced connector-cache/custom workflows, while preserving tool/write/bash mode gates.
+- Hardened direct HTTP auth defaults, local `--no-auth`, token redaction, search parsing, selected-path Pro exports, and handoff polling state.
+- Added `npm run stress` to cover full-mode MCP behavior, supertool dispatch, skill caps, card payloads, search edge cases, Pro export, and handoff polling.
+- Fixed CLI env precedence so `CODEXFLOW_HOST` / `CODEXFLOW_PORT` override generic `HOST` / `PORT`, preventing ambient process env from widening a launcher-validated bind.
+- Normalized stable public hostnames in CLI settings/setup/start flows and accepted common `--flag=value` syntax.
+
+- Made ChatGPT tool-card descriptor metadata opt-in with `CODEXFLOW_TOOL_CARDS=1`, so default `tools/list` responses stay plain MCP and avoid fragile widget metadata during tool discovery.
+- Added `codexflow loop-handoff` for bounded local execute/review loops over `.ai-bridge/current-plan.md`, with a required local `--review-command`, `--max-iters`, dry-run preview, optional test command capture, and stop conditions for no diff, repeated diff, missing follow-up plans, reviewer errors, and human cancellation.
+- Hardened `loop-handoff` external-command boundaries: commands are preflighted before execution, reviewer verdicts require explicit `CODEXFLOW_REVIEW=...` assignment lines by default, and reviewer `PASS` no longer masks failed executor/test/reviewer commands unless the user opts into the supported override behavior.
+- Fixed loop change detection so `--stop-if-no-files-changed` and `--stop-if-same-diff` compare each iteration against a pre-execution baseline and count unstaged diffs, staged diffs, and untracked file fingerprints outside `.ai-bridge`.
+- Switched loop guard decisions to an uncapped git-state fingerprint instead of hashing or vetoing on the trimmed reviewer diff artifact.
+- Kept handoff plan hashing on the handoff read-size budget instead of `--max-output-bytes`, so valid plans larger than captured output excerpts do not abort the loop after execution.
+- Made loop change fingerprints content/status based instead of timestamp based, so repeated identical tracked-file writes stop as no new changes instead of looking different because of volatile mtimes.
+- Normalized Git porcelain paths back to workspace-relative paths before loop clean-start filtering and change fingerprinting, with path-scoped status and untracked-file scans so nested workspaces inside larger Git repos are handled correctly.
+- Bounded untracked file fingerprinting so symlinks are reported via `readlink` and regular files hash only a capped prefix instead of following arbitrary paths or reading entire generated artifacts.
+- Tightened `--require-clean-git-start` so staged renames are treated as handoff-only only when both rename endpoints are inside `.ai-bridge`.
+- Stopped reviewer `FAIL` and implicit review verdicts from continuing when the reviewer deletes, empties, or restores `.ai-bridge/current-plan.md` to the scaffold instead of writing a usable follow-up plan.
+- Kept the autonomous handoff loop CLI-only and local-terminal-owned; it does not expose agent execution as a remote MCP tool, automate ChatGPT Web, approve product prompts, proxy models, or bypass limits.
+- Extended handoff smoke coverage with a fake reviewer that fails once by writing a follow-up plan, then passes on the second local executor iteration, plus failed executor, failed reviewer, bare `PASS`, staged-only, untracked-file, bounded-untracked, dirty-baseline, repeated-identical-write, nested-workspace, nested-untracked-workspace, outside-untracked-nested-workspace, large-dirty-baseline, unavailable-diff-artifact, large-plan-over-output-cap, staged-rename, deleted-follow-up-plan, and implicit-deleted-plan cases.
+
+## 0.28.5
+
+- Added a compatibility alias for stale ChatGPT descriptors that still request `ui://widget/codexflow-tool-card-v8.html`, while keeping `ui://widget/codexflow-tool-card-v9.html` as the current advertised widget.
+- Stopped advertising the `bash` MCP tool when `CODEXFLOW_BASH_MODE=off` / `codexflow --no-bash` is active, so ChatGPT has less opportunity to attempt a shell tool call in no-bash sessions.
+- Stopped advertising direct `write` and `edit` tools unless `CODEXFLOW_WRITE_MODE=workspace`; handoff/off modes keep handoff planning tools available for bounded `.ai-bridge` plan files without exposing generic source edit actions.
+- Added smoke coverage that compares `codexflow_self_test` expected tools against the actually registered MCP tool set, so disabled tools cannot silently remain visible in ChatGPT's tool list.
+- Tightened `CODEXFLOW_CONTEXT_DIR` to workspace-relative hidden directories such as `.ai-bridge`, rejecting source/build/dependency/credential directories and absolute paths.
+- Made saved profile handling stricter: non-agent modes cannot inherit `write=workspace`, relative tunnel config/token paths resolve from the workspace, and `settings set` refuses to persist raw Cloudflare tunnel tokens.
+- Completed the local admin profile form for named Cloudflare/ngrok settings, including tunnel name, config paths, token-file path, and cloudflared auto-install preference.
+- Fixed path-scoped `show_changes` so unrelated workspace status is not reported for a clean requested path.
+- Kept duplicate `load_skill` matches ambiguous until the caller supplies the exact displayed skill path.
+- Added `codexflow_self_test`, a local-only diagnostic that checks modes, expected tools, safe bash policy, selected-only Pro context, and an optional `.ai-bridge/codexflow-self-test.md` write/edit probe without touching source files.
+- Upgraded ChatGPT cards to `ui://widget/codexflow-tool-card-v9.html` and attached compact card metadata to every CodexFlow tool, with large git/tree/context/bash payloads folded or bounded instead of printed as a giant chat block.
+- Added `include_important_files` and `include_changed_files` controls to `export_pro_context` plus CLI smoke coverage for exact selected-only bundles.
+- Added a dedicated compact `server_config` renderer and accepted model-friendly aliases `workspace_snapshot.max_files` plus `git_diff.include_diff=false` to reduce avoidable retry/error loops in ChatGPT.
+- Reconfirmed the compliance boundary in runtime diagnostics and docs: CodexFlow is a local workspace MCP bridge, not a model provider, model proxy, quota bypass, resale layer, or remote executor.
+- Added `codexflow --no-bash` and documented that CodexFlow does not bind MCP bash to a Codex app conversation id.
+- Added an optional bash session guard with `--bash-session <id> --require-bash-session`; guarded `bash` calls must include the matching `session_id` before any shell command runs.
+- Made bash chat transcripts compact by default, with `--bash-transcript full` for the old raw stdout/stderr chat output.
+- Added opt-in local Codex session discovery with `--codex-sessions metadata|read`, including session ids, titles, cwd paths, source files, resume commands, and bounded transcript reads only in explicit `read` mode.
+- Added a token-protected local profile editor at `/admin/profile` and the setup page so users can save tunnel, hostname, port, mode, bash, Codex session, write/tool mode, widget origin, and tunnel config defaults for the next `codexflow` without exposing raw tokens in the browser.
+
+## 0.28.4
+
+- Made workspace cards compact by default, moving git details, discovered skills, and optional file tree output behind collapsible disclosure rows.
+- Changed workspace open skill discovery to include workspace, user, and plugin skills by default while still exposing a focused `standard` tool surface.
+- Added read-only `load_skill` so ChatGPT can load bounded `SKILL.md` instructions for discovered workspace, user, or plugin skills without exposing arbitrary path reads.
+- Kept AGENTS detection in the workspace open result but stopped embedding the full AGENTS file in the open response; agents can read it explicitly when needed.
+- Fixed setup propagation for `--widget-domain` and corrected workspace-card git status splitting for multi-file diffs.
+
+## 0.28.3
+
+- Added `CODEXFLOW_WIDGET_DOMAIN` and the Apps SDK resource metadata keys `_meta.ui.domain` plus `_meta["openai/widgetDomain"]` so ChatGPT no longer reports that the widget domain is missing.
+- Surfaced the widget domain in server config, HTTP status output, docs, env examples, and smoke tests.
+
+## 0.28.2
+
+- Moved ChatGPT visual cards from `bash` to the workspace open tools so the first call gives a compact project orientation instead of noisy terminal cards.
+- Kept `bash` data-only for focused verification commands and strengthened server instructions to prefer `tree`, `search`, `read`, and `show_changes` for inspection/review.
+- Upgraded the widget to v8 with a workspace summary renderer and a neutral waiting state instead of a stale-looking running card.
+
+## 0.28.1
+
+- Added `CODEXFLOW_TOOL_MODE=minimal|standard|full`, with `standard` as the default focused ChatGPT tool surface and `full` preserving the previous advanced toolbox.
+- Added `show_changes` as a review-oriented visual card for git status, diff stats, and optional diff while keeping raw `git_diff` data-only.
+- Upgraded the ChatGPT widget to v7 with compact bash execution summaries, review cards, and cleaner handoff cards.
+- Allowed `open_workspace` to accept `path` as an alias for `root` to reduce client argument mismatch failures.
+- Allowed safe package scripts with colon suffixes such as `npm run build:clients` for build/test verification.
+- Surfaced tool mode in server config, local status, workspace/context exports, launcher output, setup profiles, and docs.
+
+## 0.28.0
+
+- Added `codexflow execute-handoff` as an opt-in local executor for `.ai-bridge/current-plan.md`.
+- Added `codexflow watch-handoff` as an opt-in local watcher that executes new handoff plans by content hash without exposing execution as a remote MCP tool.
+- Added built-in local adapters for `opencode`, `pi`, and `codex`, plus a restricted `--command` template path for custom agents.
+- Added `--dry-run`, `--yes`, timeout handling, stdout/stderr capture, `agent-status.md`, `implementation-diff.patch`, and `execution-log.jsonl` output.
+- Kept `handoff_to_agent` planning-only; local execution is not exposed as a remote MCP tool.
+- Fixed Windows release-gate coverage for symlink-escape smoke tests, Bash lookup, and custom executor paths containing spaces.
+- Added smoke coverage for dry-run previews, custom command validation, execution status, diff collection, duplicate watch-plan skipping, and structured execution logging.
+- Clarified that CodexFlow is an official Developer Mode/MCP workflow, not a rate-limit bypass or model access provider.
+
+## 0.27.2
+
+- Added `handoff_to_agent` for file-based handoffs to Codex, OpenCode, Pi, or custom local implementation agents without executing local commands.
+- Extended `.ai-bridge` with generic `agent-status.md`, `implementation-diff.patch`, and `execution-log.jsonl` files.
+- Updated `read_handoff`, `codex_context`, Pro apply logging, docs, and smoke coverage for generic agent handoffs.
+- Fixed secret detection so benign env-var references like `process.env.TOKEN` are not blocked or redacted as literal secrets.
+- Shell-quoted generated agent command hints so model names cannot inject extra shell tokens.
+- Bounded append-mode handoff reads with the configured text-file size guard.
+
+## 0.27.1
+
+- Fail closed when HTTP MCP auth is required but `CODEXFLOW_HTTP_TOKEN` is missing, including public tunnel mode and non-loopback binds.
+- Block additional safe-bash bypass paths for absolute paths, parent paths, environment expansion, sensitive paths, and `find` write/action flags.
+- Added smoke coverage for the missing-token HTTP startup failure and safe-bash blocked command cases.
+
+## 0.27.0
+
+- Kept terminal startup focused on only the connector URL and essential controls; usage prompts now belong in README/docs only.
+- Made `git_diff` data-only instead of a widget-rendered tool. This reduces noisy ChatGPT cards and avoids template fetch failures for empty/no-op diffs.
+- Kept visual cards scoped to high-signal outputs: source writes, exact edits, Pro context exports, and Codex handoffs.
+- Updated smoke coverage so routine inspection tools stay compact.
+
+## 0.26.0
+
+- Removed prompt management from the terminal control panel.
+- Removed the `s` hotkey and all launcher-side suggested prompt generation.
+- Kept usage prompts and workflow examples in documentation instead of runtime UI.
+
+## 0.25.0
+
+- Simplified the ready screen so startup shows one compact status block instead of a long boxed next-step panel.
+- Reduced visible controls to the common actions: open ChatGPT, copy URL, open status, copy prompt, help, and quit.
+- Changed the `s` control to copy the suggested ChatGPT prompt instead of printing the full prompt repeatedly.
+- Cleaned up saved setup list formatting so reused ngrok/Cloudflare profiles are easier to scan in narrow terminals.
+
+## 0.24.0
+
+- Added `codexflow settings list` to show all saved workspace tunnel profiles.
+- Added `codexflow settings use` and `--from-root` to copy a saved setup from one workspace to another.
+- Improved first-run `codexflow` behavior: if the current workspace has no settings but other saved setups exist, CodexFlow shows them as a numbered list so users can reuse an existing ngrok or Cloudflare setup instead of retyping hostnames.
+- Expanded settings smoke coverage for profile listing and reuse.
+
+## 0.23.0
+
+- Added a compact first-run tunnel picker to `codexflow` when no workspace settings exist, so users can choose Cloudflare quick, ngrok, Cloudflare stable, or local mode without running the full setup wizard.
+- Added `codexflow settings` with `show`, `set`, and `delete --yes` actions for persistent per-workspace tunnel preferences.
+- Persisted the selected tunnel provider, hostname, port, mode, and CodexFlow token until the user changes or deletes the workspace settings.
+- Added `scripts/settings-smoke.mjs` and included it in `npm run smoke`.
+
+## 0.22.0
+
+- Added the v5 Apps SDK widget resource at `ui://widget/codexflow-tool-card-v5.html` with cleaner pending states and more polished diff/search/code cards.
+- Added a token-protected local admin dashboard at `/` and `/setup` for workspace, mode, allowed-root, setup, profile, and ChatGPT connection visibility.
+- Added the terminal `o` control to open the local admin dashboard while CodexFlow is running.
+- Updated HTTP smoke coverage to verify the onboarding page and v5 widget resource.
+
+## 0.21.0
+
+- Added `codexflow doctor` as a read-only setup diagnostic for Node, build artifacts, workspace profiles, port availability, tunnel prerequisites, clipboard support, and browser-open support.
+- Added `scripts/doctor-smoke.mjs` and included it in `npm run smoke`.
+- Added `PUBLIC_LAUNCH_CHECKLIST.md` with release gates, ChatGPT Developer Mode golden prompts, security checks, onboarding expectations, and current non-goals.
+- Added `npm run doctor` and included the public launch checklist in the npm package surface.
+
+## 0.20.0
+
+- Made `codexflow` prompts clearer with a dim "Enter to proceed with default" hint before each defaulted input.
+- Simplified the ready screen: the Server URL is described as already copied, and Enter is clearly labeled as opening ChatGPT connector settings.
+- Added saved-profile hints so ngrok/Cloudflare stable setups tell users that future launches from the same workspace only need `codexflow`.
+- Added a local port preflight with clear guidance for running two repositories at the same time.
+- Documented the multi-repo rule: each concurrent repo needs its own local port, and stable public tunnels need separate hostnames.
+
+## 0.19.0
+
+- Added per-workspace saved profiles under `~/.codexflow/profiles/`.
+- `codexflow` now saves tunnel provider, hostname, port, mode, and a generated reusable CodexFlow auth token by default.
+- `codexflow` now loads the saved profile for the current workspace unless `--no-profile` is passed.
+- Added `--save-config`, `--no-save-config`, and `--no-profile` launcher flags.
+
+## 0.18.0
+
+- Added ngrok as a first-class tunnel mode with `codexflow ngrok --hostname <domain>` and `--tunnel ngrok`.
+- Added ngrok support to the interactive `codexflow` public URL choices.
+- Added ngrok executable/config resolution with clear setup errors for missing auth or unavailable domains.
+- Documented reserved ngrok domains as a stable ChatGPT connector URL option.
+
+## 0.17.0
+
+- Added `codexflow` / `codexflow onboard` as an interactive onboarding wizard for workspace, port, mode, and public URL strategy.
+- Reworked the launcher startup and ready screens into compact framed panels with status lines instead of long setup text.
+- Added `npm run connect:setup` for source checkouts.
+- Documented the guided onboarding path next to the one-command `codexflow` flow.
+
+## 0.16.0
+
+- Reworked the widget pre-result state so in-progress tool calls show a compact running card instead of raw placeholder JSON.
+- Added `codexflow stable` and `--stable` as shortcuts for Cloudflare named-tunnel mode.
+- Added `codexflow stable-help` and friendlier missing-hostname guidance for fixed ChatGPT app URLs.
+- Updated setup docs around stable URLs for users who cannot edit an existing ChatGPT app connector URL.
+
+## 0.15.0
+
+- Changed `codexflow` to default to agent mode with workspace writes enabled.
+- Added `--mode agent`, `--mode handoff`, `--mode pro`, plus shortcut flags `--agent`, `--handoff`, and `--pro-planning`.
+- Reworked the terminal startup panel to copy the Server URL, hide long setup details by default, and expose details through controls.
+- Updated the default suggested ChatGPT prompt so ChatGPT edits/writes/verifies directly instead of creating a handoff plan.
+- Kept handoff and Pro-context workflows as explicit modes for planning-only use.
+
+## 0.14.0
+
+- Added cross-platform `cloudflared` bootstrap for macOS, Windows, and Linux.
+- CodexFlow now reuses `cloudflared` from PATH first, then `~/.codexflow/bin`, then downloads the official Cloudflare release into `~/.codexflow/bin` when needed.
+- Changed `--install-cloudflared` to force a user-local reinstall instead of using Homebrew.
+- Added `codexflow install-cloudflared` for stable-domain setup without starting the MCP server.
+- Kept `--no-install-cloudflared` as the opt-out for locked-down or manually managed machines.
+- Updated setup docs with OS-specific notes for clipboard, browser opening, and Cloudflare Tunnel.
+
+## 0.13.0
+
+- Added an interactive CodexFlow terminal control panel after startup.
+- Added Enter-to-open ChatGPT connector settings, `c` to copy URL, `p` to print app fields, `s` to print the suggested prompt, and `q` to stop.
+- Quieted local MCP and Cloudflare logs by default so startup reads like a product flow.
+- Made macOS/Homebrew `cloudflared` installation automatic by default when missing.
+- Added `--no-install-cloudflared` to opt out of automatic installation.
+- Changed the default user-facing start command to `npx codexflow@latest start`.
+
+## 0.12.0
+
+- Added clipboard-first `codexflow Start` flow for ChatGPT Developer Mode.
+- Public HTTPS connector URLs are copied automatically when clipboard support is available.
+- Added `--open-chatgpt`, `--copy-url`, and `--no-copy-url` launcher flags.
+- Added opt-in `--install-cloudflared` for macOS/Homebrew users.
+- Added `npm run connect:chatgpt` for source checkouts.
+- Updated README setup path around one command: `npx codexflow@latest start --open-chatgpt`.
+
+## 0.11.0
+
+- Renamed the package, CLI, app labels, widget metadata, and environment variables to CodexFlow.
+- Removed the duplicate CLI binary entry from `package.json`.
+- Added `DOMAIN_SETUP.md` with Namecheap, Cloudflare, stable tunnel, and future hosted-relay guidance.
+- Changed the generated model fallback bundle title to `codexflow Context Bundle`.
+- Regenerated build output and package lock metadata for the CodexFlow package name.
+
+## 0.10.0
+
+- Prepared the project for public open-source use.
+- Added npm package metadata, keywords, engine requirements, public package files, and `prepack`.
+- Added `codexflow` as a package-name binary so `npx codexflow@latest ...` works.
+- Added `codexflow pro-bundle` and `codexflow pro-apply` CLI subcommands.
+- Added `LICENSE`, `SECURITY.md`, and `CONTRIBUTING.md`.
+- Removed local runtime reports from the public package surface.
+- Reworked docs to avoid private local paths and product-specific model claims.
+
+## 0.9.0
+
+- Added stable Cloudflare named-tunnel mode with `--tunnel cloudflare-named`.
+- Added `npm run connect:stable`.
+- Added support for existing tunnel names, Cloudflare dashboard tunnel tokens, token files, and cloudflared config files.
+- Added stable-host health checks before printing the ChatGPT connector URL.
+
+## 0.8.2
+
+- Fixed duplicate `AGENTS.md` loading on case-insensitive filesystems.
+- Kept `codex_context` data-only so it does not create noisy widget cards.
+
+## 0.8.1
+
+- Added `codex_context` for AGENTS-style instructions, `.ai-bridge` handoff files, git status, and optional git diff.
+
+## 0.8.0
+
+- Made widget rendering quieter by attaching visual cards only to high-signal change tools.
+- Added request and tool-call logging without printing prompts, file contents, or tokens.
+
+## 0.7.0
+
+- Reworked the Apps SDK widget into compact developer cards.
+- Kept widget CSP strict with no external fetches, fonts, scripts, images, or iframes.
+
+## 0.6.0
+
+- Added CSP metadata for ChatGPT Developer Mode widget rendering.
+- Added `codexflow_inventory` for sanitized skill and MCP server names.
+
+## 0.5.0
+
+- Added Apps SDK widget resources for selected tool outputs.
+
+## 0.4.x
+
+- Added `export_pro_context`.
+- Added terminal helpers for creating and applying planning-context bundles.
+- Added `open_current_workspace` for safer first calls from ChatGPT.

package/CHATGPT_PROMPT.md

@@ -0,0 +1,12 @@
+Use CodexFlow.
+
+Call list_projects first and show its picker. After the user chooses, call select_project and keep all later work routed to that project.
+Do not switch projects unless the user asks.
+Call codexflow_inventory only when you need local skill or MCP server names.
+Use the `codexflow` supertool only when a stable action wrapper is needed; call it with action=list_actions first.
+
+Act as a coding agent. Inspect the relevant files, make the requested source edits with write/edit, then verify with search/read/bash and show_changes when useful. Use git_status/git_diff only when CodexFlow was started with --tool-mode full.
+
+Keep changes scoped to the request. Do not use handoff_to_agent or handoff_to_codex unless I explicitly ask for planning-only handoff.
+
+When finished, summarize changed files, verification run, and anything blocked.

package/CODEX_PROMPT.md

@@ -0,0 +1,12 @@
+Read .ai-bridge/current-plan.md and execute it in small, reviewable steps.
+
+After each meaningful change, update .ai-bridge/agent-status.md with:
+
+- what changed
+- files touched
+- tests, lint, or typecheck commands run
+- results
+- blockers or questions
+- what ChatGPT or another reviewer should review next
+
+Keep .ai-bridge/decisions.md aligned with implementation choices. Do not overwrite .ai-bridge/current-plan.md unless explicitly asked.

package/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# Contributing
+
+codexflow is early. Good contributions make it safer, faster, and easier to explain.
+
+## Local Setup
+
+```bash
+npm install
+npm run build
+npm run smoke
+```
+
+Run a local connector:
+
+```bash
+npm run connect:local -- --root /path/to/test/repo
+```
+
+Run through a Cloudflare quick tunnel:
+
+```bash
+npm run connect -- --root /path/to/test/repo --bash safe --write handoff
+```
+
+## Useful Areas
+
+- safer tool defaults
+- better setup diagnostics
+- stable tunnel setup helpers
+- smaller/faster context bundles
+- clearer ChatGPT tool prompts
+- better Apps SDK widgets
+- tests for path guards and auth boundaries
+- docs that reduce user setup mistakes
+
+## Pull Request Checklist
+
+- Keep the change scoped.
+- Do not include local tunnel URLs, auth tokens, `.env` values, or private paths.
+- Run `npm run build`.
+- Run `npm run smoke`.
+- Update `README.md` or `CHANGELOG.md` when behavior changes.
+- Explain security impact for changes touching auth, file access, shell execution, or tunnels.
+
+## Docs Style
+
+- Be concrete.
+- Avoid hype.
+- Name the exact command, mode, flag, and failure case.
+- Make risk boundaries clear.
+- Prefer examples that use `/path/to/repo` and `codexflow.example.com`, not local machine paths.

package/DOMAIN_SETUP.md

@@ -0,0 +1,241 @@
+# CodexFlow Domain Setup
+
+This guide explains how to use a Namecheap domain, Cloudflare, or ngrok so CodexFlow can keep a stable ChatGPT connector URL.
+
+There are two different products hiding behind the phrase "one URL":
+
+- Personal stable URL: one developer runs CodexFlow locally and keeps a stable URL such as `https://mcp.example.space/mcp`.
+- Hosted relay for all users: every user gets a stable CodexFlow URL without managing Cloudflare. This requires a hosted service that routes each ChatGPT request to the correct user's local agent.
+
+The personal stable URL works now. The hosted relay is the product architecture to build before public launch.
+
+## What A Domain Can And Cannot Do
+
+A DNS hostname points traffic to one Cloudflare tunnel, load balancer, or hosted service. It cannot automatically discover every user's laptop.
+
+For public users, one shared domain needs one of these designs:
+
+- Per-user tunnel hostnames, such as `alice.mcp.example.space` and `bob.mcp.example.space`, each routed to that user's tunnel.
+- A hosted relay at `mcp.example.space` where each local CodexFlow agent opens an outbound connection and authenticates. ChatGPT calls the relay URL, and the relay forwards each request to the right connected local agent.
+
+The hosted relay is the clean end-user experience:
+
+```text
+User terminal
+  CodexFlow --root .
+  opens outbound session to your relay
+
+ChatGPT connector
+  https://mcp.example.space/<workspace-id>/mcp
+
+Relay
+  authenticates request
+  forwards MCP traffic to the correct user's local CodexFlow agent
+```
+
+That is how you make the setup feel like one URL for everyone.
+
+## Recommended Domain Layout
+
+Use subdomains instead of the apex domain:
+
+```text
+codexflow.example.space       marketing/docs site
+app.example.space            future dashboard/login
+mcp.example.space            hosted relay entrypoint
+local.example.space          optional private dogfood tunnel
+```
+
+For your current dogfood setup, use:
+
+```text
+local.example.space
+```
+
+For the future public product, use:
+
+```text
+mcp.example.space
+```
+
+## One-Time Namecheap And Cloudflare Setup
+
+1. Add your apex domain to Cloudflare.
+
+   In Cloudflare Dashboard, go to Domains, choose "Onboard a domain", enter your domain such as `example.space`, choose a plan, and review imported DNS records.
+
+2. Change Namecheap nameservers.
+
+   In Namecheap, open Domain List, choose Manage for the domain, set Nameservers to Custom nameservers, enter the two Cloudflare nameservers, and save.
+
+3. Wait for activation.
+
+   Namecheap says nameserver propagation can take up to 24-48 hours in rare cases. Cloudflare will show the domain as active once the nameservers are picked up.
+
+4. Preserve email records.
+
+   If the domain receives email, make sure MX, SPF, DKIM, and DMARC records exist in Cloudflare before relying on the domain.
+
+## Personal Stable Tunnel
+
+Install or bootstrap `cloudflared`:
+
+```bash
+codexflow install-cloudflared
+```
+
+That installs the official Cloudflare binary into `~/.codexflow/bin` on supported macOS, Windows, and Linux machines. You can also install `cloudflared` manually and keep it on PATH.
+
+Authenticate:
+
+```bash
+~/.codexflow/bin/cloudflared tunnel login
+```
+
+Create a named tunnel:
+
+```bash
+~/.codexflow/bin/cloudflared tunnel create codexflow-local
+~/.codexflow/bin/cloudflared tunnel route dns codexflow-local local.example.space
+```
+
+Start CodexFlow with that stable hostname:
+
+```bash
+codexflow stable \
+  --root /absolute/path/to/your/repo \
+  --hostname local.example.space \
+  --tunnel-name codexflow-local \
+  --token replace-with-a-long-stable-token \
+  --bash safe
+```
+
+Add this once in ChatGPT Developer Mode:
+
+```text
+Name: CodexFlow
+Connection: Server URL
+Server URL: https://local.example.space/mcp?codexflow_token=replace-with-a-long-stable-token
+Authentication: None / No Authentication
+```
+
+After that, restart only the terminal command. You do not need to edit the ChatGPT connector unless you change the hostname or token.
+
+## Dashboard-Managed Tunnel Token
+
+If you create the tunnel in the Cloudflare dashboard, save the connector token locally:
+
+```bash
+mkdir -p ~/.codexflow
+chmod 700 ~/.codexflow
+$EDITOR ~/.codexflow/cloudflare-tunnel-token
+chmod 600 ~/.codexflow/cloudflare-tunnel-token
+```
+
+Then run:
+
+```bash
+codexflow stable \
+  --root /absolute/path/to/your/repo \
+  --hostname local.example.space \
+  --cloudflare-token-file ~/.codexflow/cloudflare-tunnel-token \
+  --token replace-with-a-long-stable-token \
+  --bash safe
+```
+
+Do not confuse these two tokens:
+
+```text
+Cloudflare tunnel token  lets cloudflared connect your machine to Cloudflare.
+codexflow MCP token       protects the /mcp endpoint that ChatGPT calls.
+```
+
+## Ngrok Free Dev Domain
+
+Ngrok is the simpler personal stable URL for most users. A free ngrok account includes a dev domain, which can be saved once in CodexFlow and reused every time the local server restarts.
+
+One-time setup:
+
+```bash
+brew install ngrok
+ngrok config add-authtoken <your-ngrok-token>
+```
+
+Find your assigned dev domain in the ngrok dashboard under Universal Gateway -> Domains, for example:
+
+```text
+your-domain.ngrok-free.dev
+```
+
+Daily startup:
+
+```bash
+codexflow ngrok \
+  --root /absolute/path/to/your/repo \
+  --hostname your-domain.ngrok-free.dev \
+  --token replace-with-a-long-stable-token \
+  --bash safe
+```
+
+Add this once in ChatGPT Developer Mode:
+
+```text
+Name: CodexFlow
+Connection: Server URL
+Server URL: https://your-domain.ngrok-free.dev/mcp?codexflow_token=replace-with-a-long-stable-token
+Authentication: None / No Authentication
+```
+
+CodexFlows the local MCP server, runs `ngrok http http://127.0.0.1:8787 --url https://your-domain.ngrok-free.dev`, waits for `/healthz`, copies the Server URL, and keeps both processes alive until you quit.
+
+## Product Plan For All Users
+
+For open-source users, support three modes:
+
+```text
+1. Local-only stdio/HTTP
+   No public URL. Best for clients that can launch local MCP commands.
+
+2. Bring-your-own tunnel
+   User owns Cloudflare/ngrok/domain. Good for power users and contributors.
+
+3. CodexFlow hosted relay
+   Best public UX. User runs one local command and gets a stable connector URL from your service.
+```
+
+The hosted relay needs:
+
+- User auth and device registration.
+- Per-device or per-workspace MCP URLs.
+- Local agent outbound WebSocket or HTTP/2 session to the relay.
+- Per-session CodexFlow token rotation.
+- Audit log of tool names, durations, and file paths, without source contents by default.
+- Strict write modes: `workspace` by default for agent mode, `handoff` when the user chooses planning-only mode.
+- Workspace root allowlist enforced locally, not only at the relay.
+- Revocation from the dashboard.
+
+## Latency And Cost
+
+For your own named tunnel, latency should be similar to the current quick tunnel. The domain itself does not add meaningful latency; traffic still goes through Cloudflare Tunnel.
+
+For the hosted relay, there is one extra hop:
+
+```text
+ChatGPT -> Cloudflare/relay -> user's local CodexFlow agent
+```
+
+That is usually fine for planning and file operations. The bigger speed win is reducing tool calls and response payloads:
+
+- Start with `open_current_workspace` and `include_tree=false`.
+- Use targeted `read`, `search`, and `codex_context`.
+- Show widget cards only for high-signal write/edit/diff results.
+- Keep `server_config`, inventory, tree, read, and search compact.
+
+For cost, the domain renewal is separate. Cloudflare DNS and basic tunnel usage can be enough for dogfooding. A public relay will eventually cost real hosting/traffic/observability money, even if it starts small on Cloudflare Workers, Durable Objects, or a small server.
+
+## Sources
+
+- Cloudflare domain onboarding: https://developers.cloudflare.com/fundamentals/manage-domains/add-site/
+- Namecheap Cloudflare nameserver setup: https://www.namecheap.com/support/knowledgebase/article.aspx/9607/2210/how-to-set-up-dns-records-for-your-domain-in-a-cloudflare-account/
+- Cloudflare locally-managed tunnel: https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/do-more-with-tunnels/local-management/create-local-tunnel/
+- Cloudflare Tunnel overview: https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/