npm - @tarunspandit/codexflow - Versions diffs - 0.29.0 - Mend

@tarunspandit/codexflow 0.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (92) hide show

package/AGENTS.example.md +18 -0
package/CHANGELOG.md +311 -0
package/CHATGPT_PROMPT.md +12 -0
package/CODEX_PROMPT.md +12 -0
package/CONTRIBUTING.md +51 -0
package/DOMAIN_SETUP.md +241 -0
package/FAQ.md +327 -0
package/FAQ_ZH.md +279 -0
package/LICENSE +21 -0
package/NOTICE +9 -0
package/PUBLIC_LAUNCH_CHECKLIST.md +111 -0
package/README.md +287 -0
package/README_ZH.md +461 -0
package/SECURITY.md +145 -0
package/config.example.env +31 -0
package/dist/analysis/cache.js +27 -0
package/dist/analysis/cache.js.map +1 -0
package/dist/analysis/classify.js +102 -0
package/dist/analysis/classify.js.map +1 -0
package/dist/analysis/extract.js +139 -0
package/dist/analysis/extract.js.map +1 -0
package/dist/analysis/graph.js +22 -0
package/dist/analysis/graph.js.map +1 -0
package/dist/analysis/impact.js +167 -0
package/dist/analysis/impact.js.map +1 -0
package/dist/analysis/index.js +215 -0
package/dist/analysis/index.js.map +1 -0
package/dist/analysis/inventory.js +51 -0
package/dist/analysis/inventory.js.map +1 -0
package/dist/analysis/providers.js +24 -0
package/dist/analysis/providers.js.map +1 -0
package/dist/analysis/rank.js +27 -0
package/dist/analysis/rank.js.map +1 -0
package/dist/analysis/types.js +8 -0
package/dist/analysis/types.js.map +1 -0
package/dist/bashOps.js +233 -0
package/dist/bashOps.js.map +1 -0
package/dist/capabilitiesOps.js +365 -0
package/dist/capabilitiesOps.js.map +1 -0
package/dist/codexSessions.js +379 -0
package/dist/codexSessions.js.map +1 -0
package/dist/config.js +289 -0
package/dist/config.js.map +1 -0
package/dist/fsOps.js +286 -0
package/dist/fsOps.js.map +1 -0
package/dist/gitOps.js +79 -0
package/dist/gitOps.js.map +1 -0
package/dist/guard.js +198 -0
package/dist/guard.js.map +1 -0
package/dist/http.js +1671 -0
package/dist/http.js.map +1 -0
package/dist/proContext.js +274 -0
package/dist/proContext.js.map +1 -0
package/dist/profileStore.js +89 -0
package/dist/profileStore.js.map +1 -0
package/dist/projectCatalog.js +134 -0
package/dist/projectCatalog.js.map +1 -0
package/dist/redact.js +73 -0
package/dist/redact.js.map +1 -0
package/dist/searchOps.js +186 -0
package/dist/searchOps.js.map +1 -0
package/dist/server.js +2502 -0
package/dist/server.js.map +1 -0
package/dist/stdio.js +36 -0
package/dist/stdio.js.map +1 -0
package/dist/toolCardWidget.js +1155 -0
package/dist/toolCardWidget.js.map +1 -0
package/dist/workspaceOps.js +229 -0
package/dist/workspaceOps.js.map +1 -0
package/docs/.nojekyll +1 -0
package/docs/favicon.svg +5 -0
package/docs/index.html +638 -0
package/docs/og.png +0 -0
package/docs/script.js +80 -0
package/docs/star.svg +11 -0
package/docs/styles.css +1229 -0
package/docs/zh.html +436 -0
package/package.json +94 -0
package/scripts/analysis-cli-smoke.mjs +81 -0
package/scripts/analysis-smoke.mjs +179 -0
package/scripts/clean.mjs +6 -0
package/scripts/cli-smoke.mjs +168 -0
package/scripts/codexflow.mjs +4375 -0
package/scripts/doctor-smoke.mjs +90 -0
package/scripts/execute-handoff-smoke.mjs +1110 -0
package/scripts/http-smoke.mjs +812 -0
package/scripts/pro-apply.mjs +141 -0
package/scripts/pro-bundle.mjs +121 -0
package/scripts/pro-smoke.mjs +95 -0
package/scripts/settings-smoke.mjs +756 -0
package/scripts/smoke.mjs +1194 -0
package/scripts/stress.mjs +835 -0

package/docs/index.html ADDED Viewed

@@ -0,0 +1,638 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>CodexFlow — One command. Every project. Any chat.</title>
+    <meta
+      name="description"
+      content="CodexFlow gives ChatGPT Codex-style access to synchronized local projects through one MCP broker and tunnel, with per-chat project routing, skills, files, git, and terminal tools."
+    />
+    <meta property="og:title" content="CodexFlow" />
+    <meta property="og:description" content="Use ChatGPT like a local coding agent across synchronized projects through one token-protected broker." />
+    <meta property="og:image" content="https://raw.githubusercontent.com/tarunspandit/codexflow/main/docs/og.png" />
+    <meta name="theme-color" content="#080a0c" />
+    <link rel="alternate" hreflang="zh-CN" href="./zh.html" />
+    <link rel="icon" href="./favicon.svg" type="image/svg+xml" />
+    <link rel="stylesheet" href="./styles.css?v=2" />
+  </head>
+  <body>
+    <a class="skip-link" href="#quickstart">Skip to start</a>
+    <header class="site-header">
+      <a class="brand" href="#top" aria-label="CodexFlow home">
+        <img class="brand-mark" src="./favicon.svg" width="34" height="34" alt="" aria-hidden="true" />
+        <span>CodexFlow</span>
+      </a>
+      <nav aria-label="Primary navigation">
+        <a href="#quickstart">Start</a>
+        <a href="#modes">Modes</a>
+        <a href="#reference">Tools</a>
+        <a href="#faq">FAQ</a>
+        <a href="#stop">Stop</a>
+        <a href="./zh.html">中文</a>
+        <a class="nav-star" href="https://github.com/tarunspandit/codexflow"><img src="./star.svg" alt="" aria-hidden="true" />Star on GitHub</a>
+      </nav>
+    </header>
+    <main id="top">
+      <section class="hero">
+        <div class="hero-copy">
+          <p class="launch-pill"><img src="./star.svg" alt="" aria-hidden="true" />Local-first coding infrastructure</p>
+          <p class="eyebrow">One broker · every local project · independent chats</p>
+          <h1>One command. Every project. <em>Any chat.</em></h1>
+          <p class="hero-lede">
+            Turn ChatGPT on the web into a project-aware coding agent for your local machine. One broker discovers your projects, one tunnel connects them, and every conversation keeps its own workspace—without invoking the Codex CLI.
+          </p>
+          <div class="install-line" role="group" aria-label="Install command">
+            <code>npm install -g @tarunspandit/codexflow
+codexflow</code>
+            <button class="copy-button" data-copy="npm install -g @tarunspandit/codexflow&#10;codexflow">Copy</button>
+          </div>
+          <p class="eyebrow">Independent open-source project; not affiliated with or endorsed by OpenAI.</p>
+          <div class="hero-proof" aria-label="Core capabilities">
+            <span>many projects</span>
+            <span>independent chat routing</span>
+            <span>token-protected URL</span>
+            <span>safe bash default</span>
+            <span>repo-backed context</span>
+          </div>
+          <div class="hero-actions">
+            <a class="button primary" href="#quickstart">Install CodexFlow</a>
+            <a class="button secondary star-button" href="https://github.com/tarunspandit/codexflow"><img src="./star.svg" alt="" aria-hidden="true" />Star on GitHub</a>
+            <a class="button secondary" href="https://www.npmjs.com/package/@tarunspandit/codexflow">View npm package</a>
+          </div>
+        </div>
+        <div class="hero-visual" aria-label="CodexFlow connection model">
+          <div class="workspace-demo blueprint">
+            <div class="demo-status">
+              <span class="status-dot" aria-hidden="true"></span>
+              <div class="status-label">
+                <strong>Synchronized local projects</strong>
+                <small>one broker · one tunnel · independent chats</small>
+              </div>
+              <span class="status-badge">bounded</span>
+            </div>
+            <div class="connection-map" aria-label="Connection flow">
+              <div>
+                <span>01</span>
+                <strong>Project picker</strong>
+                <p>Configured roots plus recent local Codex project folders.</p>
+              </div>
+              <div>
+                <span>02</span>
+                <strong>CodexFlow</strong>
+                <p>Routes each chat to its selected folder and advertises local skills and plugins.</p>
+              </div>
+              <div>
+                <span>03</span>
+                <strong>ChatGPT app</strong>
+                <p>Read, search, edit, review, verify, or hand off through Developer Mode.</p>
+              </div>
+            </div>
+            <div class="trust-row">
+              <div><span>Not a model proxy</span><strong>uses your own ChatGPT account</strong></div>
+              <div><span>Not a quota bypass</span><strong>product limits still apply</strong></div>
+              <div><span>Not an OS sandbox</span><strong>keep roots scoped to the repo</strong></div>
+            </div>
+          </div>
+          <div class="floating-note">
+            <span>That is the setup</span>
+            <strong>codexflow</strong>
+            <small>Run it from anywhere. Projects are discovered automatically.</small>
+          </div>
+        </div>
+      </section>
+      <section class="strip" aria-label="Core workflow">
+        <div>
+          <span>01</span>
+          <strong>Install</strong>
+          <p>Run <code>npm install -g @tarunspandit/codexflow</code> once.</p>
+        </div>
+        <div>
+          <span>02</span>
+          <strong>Run</strong>
+          <p>Type <code>codexflow</code> from anywhere.</p>
+        </div>
+        <div>
+          <span>03</span>
+          <strong>Paste</strong>
+          <p>Paste the copied Server URL when creating the ChatGPT plugin.</p>
+        </div>
+      </section>
+      <section class="section value-section">
+        <div>
+          <p class="eyebrow">Use the account you already have</p>
+          <h2>Give ChatGPT a real local workspace, not another paste buffer.</h2>
+          <p>
+            CodexFlow is for builders who already pay for ChatGPT and want that subscription to do more than answer questions. It gives ChatGPT a local workspace bridge: file reads, exact edits, source writes, search, git status, git diff, and allowlisted verification commands.
+          </p>
+          <p>
+            Codex and ChatGPT are different product surfaces. If one workflow is unavailable and another surface you already have access to is still available, CodexFlow lets you work against the same local repo without changing either product's limits.
+          </p>
+          <p>
+            If your ChatGPT account exposes a stronger model in the web app, and that model surface can call Developer Mode apps, CodexFlow lets it work against your local repo through MCP. Some model surfaces cannot call connectors or MCP tools directly. CodexFlow does not provide, proxy, resell, or unlock models; it gives compatible ChatGPT sessions local coding tools and repo context.
+          </p>
+        </div>
+        <div class="value-matrix">
+          <div>
+            <small>ChatGPT web can see</small>
+            <strong>AGENTS.md, .ai-bridge, git state, source files, and selected Codex-style context</strong>
+          </div>
+          <div>
+            <small>Normal coding mode can</small>
+            <strong>read, write, edit, search, and verify directly in the workspace</strong>
+          </div>
+          <div>
+            <small>Pro planning mode can</small>
+            <strong>export a durable context bundle for sessions where MCP tools are unavailable</strong>
+          </div>
+          <div>
+            <small>Best account fit</small>
+            <strong>ChatGPT account with Apps / Developer Mode access. OpenAI lists Developer Mode for Pro, Plus, Business, Enterprise, and Education on web; Free and Go do not expose this app flow in current testing.</strong>
+          </div>
+        </div>
+      </section>
+      <section id="execute" class="section two-col">
+        <div>
+          <p class="eyebrow">Planner to executor</p>
+          <h2>Let ChatGPT plan, then run a local agent on your machine.</h2>
+          <p>
+            Handoff mode keeps ChatGPT planning-only. ChatGPT writes <code>.ai-bridge/current-plan.md</code>, then you decide whether to run a local implementation agent from your terminal.
+          </p>
+          <p>
+            <code>codexflow execute-handoff</code> runs the saved plan through OpenCode, Pi, Codex, or a custom command, then collects status, stdout/stderr excerpts, and the final git diff back into <code>.ai-bridge</code> for ChatGPT review.
+          </p>
+        </div>
+        <div class="command-stack">
+          <div>
+            <small>Preview first</small>
+            <pre><code>codexflow execute-handoff --agent opencode --model provider/model --dry-run</code></pre>
+          </div>
+          <div>
+            <small>Run locally</small>
+            <pre><code>codexflow execute-handoff --agent opencode --model provider/model</code></pre>
+          </div>
+          <div>
+            <small>Custom agent</small>
+            <pre><code>codexflow execute-handoff --agent custom --command "my-agent --task-file {{plan_file}}"</code></pre>
+          </div>
+          <div>
+            <small>Result files</small>
+            <pre><code>.ai-bridge/agent-status.md
+.ai-bridge/implementation-diff.patch
+.ai-bridge/execution-log.jsonl</code></pre>
+          </div>
+        </div>
+      </section>
+      <section class="section two-col">
+        <div>
+          <p class="eyebrow">Compared with generic workspace bridges</p>
+          <h2>CodexFlow is the ChatGPT-first local coding loop.</h2>
+          <p>
+            CodexFlow runs one local MCP broker and tunnel for many repositories. Every ChatGPT MCP connection keeps its own selected project, so parallel chats can work in different folders without launching another broker.
+          </p>
+          <p>
+            That means automatic project discovery, explicit safety modes, repo-backed context files, reviewable diffs, compact cards, and no model proxying, account pooling, quota bypassing, third-party Pro scraping, or OS sandbox claims.
+          </p>
+        </div>
+        <div class="value-matrix">
+          <div>
+            <small>Product loop</small>
+            <strong>Install once, save a projects root, paste one Server URL, then select a folder per chat.</strong>
+          </div>
+          <div>
+            <small>Control surface</small>
+            <strong>Bash, write/edit, tool mode, Codex session reads, and handoff execution are separate switches.</strong>
+          </div>
+          <div>
+            <small>Context model</small>
+            <strong>AGENTS.md and .ai-bridge keep durable project memory in files you can review.</strong>
+          </div>
+          <div>
+            <small>Trust model</small>
+            <strong>Your ChatGPT account, your local repo, your explicit tunnel and token.</strong>
+          </div>
+        </div>
+      </section>
+      <section id="quickstart" class="section two-col">
+        <div>
+          <p class="eyebrow">Quick start</p>
+          <h2>Install once. Type CodexFlow. Done.</h2>
+          <p>
+            The bare command discovers projects from local Codex metadata, starts normal coding mode with safe bash, opens a Cloudflare quick tunnel, copies the connection URL, and waits for ChatGPT.
+          </p>
+        </div>
+        <div class="steps">
+          <div class="step">
+            <span>1</span>
+            <div>
+              <strong>Install globally</strong>
+              <pre><code>npm install -g @tarunspandit/codexflow</code></pre>
+            </div>
+          </div>
+          <div class="step">
+            <span>2</span>
+            <div>
+              <strong>Start everything</strong>
+              <pre><code>codexflow</code></pre>
+            </div>
+          </div>
+          <div class="step">
+            <span>3</span>
+            <div>
+              <strong>Turn on Developer Mode</strong>
+              <p>In ChatGPT, open Settings -> Security and login. Turn on Developer mode and keep Enforce CSP in developer mode enabled, then go to Settings -> Plugins and create the connection.</p>
+            </div>
+          </div>
+          <div class="step">
+            <span>4</span>
+            <div>
+              <strong>Create a ChatGPT plugin</strong>
+              <p>Name it CodexFlow. Use Connection: Server URL. Paste the copied URL. Set Authentication to No Authentication / None.</p>
+            </div>
+          </div>
+          <div class="step">
+            <span>5</span>
+            <div>
+              <strong>Use CodexFlow in chat</strong>
+              <p>Activate CodexFlow, choose a project in the picker, then ask ChatGPT to inspect, edit, and verify. Each chat keeps its own project selection.</p>
+            </div>
+          </div>
+        </div>
+      </section>
+      <section class="section">
+        <div class="section-heading">
+          <p class="eyebrow">Tunnel choices</p>
+          <h2>Pick the URL strategy that matches your workflow.</h2>
+        </div>
+        <div class="compare-grid">
+          <article>
+            <span class="tag">Fastest</span>
+            <h3>Cloudflare quick tunnel</h3>
+            <p>No account flow. Good for demos. The URL changes every restart, so you must update the ChatGPT app Server URL each time.</p>
+            <pre><code>codexflow</code></pre>
+          </article>
+          <article>
+            <span class="tag">Recommended</span>
+            <h3>ngrok free dev domain</h3>
+            <p>Best simple stable URL. Create a free ngrok account, use the assigned dev domain, and keep the same ChatGPT app URL across restarts.</p>
+            <pre><code>codexflow ngrok --hostname your-name.ngrok-free.dev</code></pre>
+          </article>
+          <article>
+            <span class="tag">Custom</span>
+            <h3>Cloudflare named tunnel</h3>
+            <p>Use your own domain, such as <code>codexflow.example.com</code>, and keep one ChatGPT URL.</p>
+            <pre><code>codexflow stable --hostname codexflow.example.com --tunnel-name codexflow</code></pre>
+          </article>
+          <article>
+            <span class="tag">Tailnet</span>
+            <h3>Tailscale Funnel</h3>
+            <p>Use your device's <code>.ts.net</code> hostname when your tailnet already allows public Funnel HTTPS.</p>
+            <pre><code>codexflow tailscale --hostname your-device.your-tailnet.ts.net</code></pre>
+          </article>
+        </div>
+      </section>
+      <section id="ngrok" class="section two-col">
+        <div>
+          <p class="eyebrow">ngrok setup</p>
+          <h2>Use ngrok's free dev domain for a fixed ChatGPT connector URL.</h2>
+          <p>
+            ngrok free accounts include a dev domain. Find it in the ngrok dashboard under Universal Gateway -> Domains, save it once in CodexFlow, and future starts from the same repo are just <code>codexflow</code>.
+          </p>
+          <p>
+            That means users do not need to change ChatGPT settings every time they restart CodexFlow.
+          </p>
+        </div>
+        <div class="command-stack">
+          <div>
+            <small>One-time ngrok auth</small>
+            <pre><code>ngrok config add-authtoken YOUR_NGROK_TOKEN</code></pre>
+          </div>
+          <div>
+            <small>Save the CodexFlow workspace profile</small>
+            <pre><code>codexflow settings set --tunnel ngrok --hostname your-name.ngrok-free.dev</code></pre>
+          </div>
+          <div>
+            <small>Daily start</small>
+            <pre><code>codexflow</code></pre>
+          </div>
+        </div>
+      </section>
+      <section id="cloudflare" class="section two-col reverse">
+        <div class="command-stack">
+          <div>
+            <small>Quick tunnel</small>
+            <pre><code>codexflow --tunnel cloudflare</code></pre>
+          </div>
+          <div>
+            <small>Named tunnel with your domain</small>
+            <pre><code>cloudflared tunnel login
+cloudflared tunnel create CodexFlow
+cloudflared tunnel route dns CodexFlow codexflow.example.com</code></pre>
+          </div>
+          <div>
+            <small>Daily stable start</small>
+            <pre><code>codexflow stable --hostname codexflow.example.com --tunnel-name codexflow</code></pre>
+          </div>
+        </div>
+        <div>
+          <p class="eyebrow">Cloudflare setup</p>
+          <h2>Start instantly with quick tunnels or keep a custom domain with named tunnels.</h2>
+          <p>
+            CodexFlow can install <code>cloudflared</code> into <code>~/.codexflow/bin</code> when it is missing. No sudo, Homebrew, apt, or winget step is required for the default path.
+          </p>
+          <p>
+            Quick tunnels are disposable. If you own a domain, use a Cloudflare named tunnel and route DNS to a hostname such as <code>codexflow.example.com</code>. The hostname stays the same across restarts, so the ChatGPT app Server URL does not need to change.
+          </p>
+        </div>
+      </section>
+      <section id="modes" class="section">
+        <div class="section-heading">
+          <p class="eyebrow">Modes</p>
+          <h2>Use the right level of control for the task.</h2>
+        </div>
+        <div class="mode-row">
+          <div>
+            <strong>Normal coding</strong>
+            <p>Default. ChatGPT can inspect, write, edit, search, and verify inside the workspace.</p>
+          </div>
+          <div>
+            <strong>Handoff</strong>
+            <p>Planning-only. ChatGPT writes <code>.ai-bridge/current-plan.md</code> and Codex executes locally.</p>
+          </div>
+          <div>
+            <strong>Pro planning</strong>
+            <p>Exports a durable context file for models or surfaces that cannot call connectors or MCP tools directly.</p>
+          </div>
+        </div>
+      </section>
+      <section id="reference" class="section reference-section">
+        <div class="section-heading">
+          <p class="eyebrow">Complete setup data</p>
+          <h2>Everything needed to install, connect, use, and stop CodexFlow.</h2>
+          <p>
+            This page keeps the high-signal details in one place: commands, ChatGPT app fields, tunnel choices, tools, saved settings, safety defaults, and useful links.
+          </p>
+        </div>
+        <div class="reference-grid">
+          <article>
+            <small>Install</small>
+            <h3>Install globally once</h3>
+            <pre><code>npm install -g @tarunspandit/codexflow</code></pre>
+            <p>This gives users the simple <code>codexflow</code> command everywhere.</p>
+          </article>
+          <article>
+            <small>First run</small>
+            <h3>Automatic start</h3>
+            <pre><code>codexflow</code></pre>
+            <p>The bare command needs no saved workspace profile. Advanced tunnel and safety overrides remain available as optional flags.</p>
+          </article>
+          <article>
+            <small>Daily start</small>
+            <h3>Reuse saved profile</h3>
+            <pre><code>codexflow</code></pre>
+            <p>Every run refreshes the Codex project catalog automatically.</p>
+          </article>
+          <article>
+            <small>ChatGPT settings path</small>
+            <h3>Enable plugins once</h3>
+            <dl>
+              <div><dt>Open</dt><dd>ChatGPT Settings</dd></div>
+              <div><dt>Go to</dt><dd>Security and login</dd></div>
+              <div><dt>Enable</dt><dd>Developer mode</dd></div>
+              <div><dt>Keep on</dt><dd>Enforce CSP in developer mode</dd></div>
+              <div><dt>Then</dt><dd>Plugins -> Create</dd></div>
+            </dl>
+            <p>This is a one-time ChatGPT setting. CodexFlow widgets work with CSP enabled.</p>
+          </article>
+          <article>
+            <small>Create Plugin fields</small>
+            <h3>Paste the copied URL</h3>
+            <dl>
+              <div><dt>Name</dt><dd>CodexFlow</dd></div>
+              <div><dt>Description</dt><dd>Local workspace bridge for ChatGPT coding</dd></div>
+              <div><dt>Connection</dt><dd>Server URL</dd></div>
+              <div><dt>Server URL</dt><dd>Paste copied CodexFlow URL</dd></div>
+              <div><dt>Authentication</dt><dd>No Authentication / None</dd></div>
+            </dl>
+            <p>The copied Server URL already includes the private CodexFlow token. Do not paste the token separately unless your ChatGPT UI supports custom headers.</p>
+          </article>
+          <article>
+            <small>Doctor</small>
+            <h3>Preflight checks</h3>
+            <pre><code>codexflow doctor</code></pre>
+            <p>Checks Node, build output, saved profile, port availability, tunnel prerequisites, clipboard support, and browser-open support.</p>
+          </article>
+          <article>
+            <small>Runtime status</small>
+            <h3>Check a running connector</h3>
+            <pre><code>codexflow status
+codexflow status --json</code></pre>
+            <p>Shows whether this workspace has an active launcher, the token-free Server URL, process id, and local health state.</p>
+          </article>
+          <article>
+            <small>Settings</small>
+            <h3>Manage saved profiles</h3>
+            <pre><code>codexflow settings
+codexflow settings set --tunnel ngrok --hostname your-name.ngrok-free.dev
+codexflow settings delete --yes</code></pre>
+            <p>Use settings to switch providers, reuse another repo setup, or delete a workspace preference.</p>
+          </article>
+          <article>
+            <small>Controls</small>
+            <h3>Terminal keys</h3>
+            <dl>
+              <div><dt>Enter</dt><dd>Open ChatGPT connector settings</dd></div>
+              <div><dt>c</dt><dd>Copy Server URL again</dd></div>
+              <div><dt>o</dt><dd>Open local admin dashboard</dd></div>
+              <div><dt>q</dt><dd>Stop CodexFlow</dd></div>
+            </dl>
+          </article>
+          <article>
+            <small>Local admin</small>
+            <h3>Setup, profile, and status</h3>
+            <p>Press <code>o</code> to open the token-protected admin dashboard. It shows install/start commands, ChatGPT connection steps, saved profile settings, modes, allowed roots, and advanced restart shortcuts.</p>
+          </article>
+        </div>
+        <div class="tool-reference">
+          <div>
+            <p class="eyebrow">Default standard tools</p>
+            <h3>Focused local repo actions exposed through MCP.</h3>
+          </div>
+          <div class="tool-list">
+            <span>CodexFlow</span>
+            <span>server_config</span>
+            <span>codexflow_self_test</span>
+            <span>list_projects</span>
+            <span>select_project</span>
+            <span>open_current_workspace</span>
+            <span>open_workspace</span>
+            <span>tree</span>
+            <span>search</span>
+            <span>read</span>
+            <span>write</span>
+            <span>edit</span>
+            <span>bash</span>
+            <span>show_changes</span>
+            <span>read_handoff</span>
+            <span>wait_for_handoff</span>
+            <span>export_pro_context</span>
+            <span>handoff_to_agent</span>
+          </div>
+        </div>
+        <div class="reference-grid compact">
+          <article>
+            <small>Multi-project routing</small>
+            <h3>One tunnel, independent chats</h3>
+            <p><code>list_projects</code> synchronizes allowed folders and recent Codex project metadata. <code>select_project</code> binds only the current ChatGPT MCP connection; later tools route there automatically.</p>
+          </article>
+          <article>
+            <small>Safety defaults</small>
+            <h3>Blocked paths</h3>
+            <p><code>.env</code>, private keys, <code>.git</code>, <code>node_modules</code>, generated build/cache folders, paths outside the workspace, and symlink escapes are refused.</p>
+          </article>
+          <article>
+            <small>Safe bash</small>
+            <h3>Verification without full shell</h3>
+            <p>Safe mode allows common repo inspection, git, tests, lint, typecheck, and build commands. Use full bash only for trusted local repos.</p>
+          </article>
+          <article>
+            <small>No surprise shell</small>
+            <h3>Disable or target bash</h3>
+            <p>Use <code>codexflow --no-bash</code>, or keep bash enabled with <code>--bash-session main --require-bash-session</code>. Session labels target this local CodexFlow server, not a Codex app chat.</p>
+          </article>
+          <article>
+            <small>Codex sessions</small>
+            <h3>Opt-in local history browser</h3>
+            <p><code>--codex-sessions metadata</code> lists local Codex session ids, titles, cwd paths, and resume commands. <code>read</code> mode adds bounded transcript reads; neither mode attaches to a live Codex chat.</p>
+          </article>
+          <article>
+            <small>Visual widgets</small>
+            <h3>Compact cards for every tool</h3>
+            <p>The project picker is always interactive. Other tools can render compact v10 cards when tool cards are enabled; skills, git, tree, terminal output, and raw diffs stay folded or bounded.</p>
+          </article>
+          <article>
+            <small>Stable URL rule</small>
+            <h3>One URL needs one reserved hostname</h3>
+            <p>Cloudflare quick tunnels change on restart. Use an ngrok free dev domain, Cloudflare named tunnel, or Tailscale Funnel when you want one ChatGPT app URL.</p>
+          </article>
+          <article>
+            <small>Local web admin</small>
+            <h3>Edit next-run profile defaults</h3>
+            <p>The token-protected local page can save tunnel, hostname, port, mode, bash, Codex sessions, write/tool mode, widget origin, and tunnel config paths for the next <code>codexflow</code>. Raw tunnel tokens, account switching, and background services stay out of the browser.</p>
+          </article>
+          <article>
+            <small>Local executor</small>
+            <h3>Execution stays on your machine</h3>
+            <p><code>execute-handoff</code> is a terminal command, not a remote MCP tool. Use <code>--dry-run</code> before running unfamiliar agents or custom commands.</p>
+          </article>
+        </div>
+        <div class="link-row" aria-label="Documentation links">
+          <a class="star-link" href="https://github.com/tarunspandit/codexflow"><img src="./star.svg" alt="" aria-hidden="true" />Star the GitHub repo</a>
+          <a href="https://www.npmjs.com/package/@tarunspandit/codexflow">npm package</a>
+          <a href="https://github.com/tarunspandit/codexflow/blob/main/DOMAIN_SETUP.md">Stable URL guide</a>
+          <a href="https://github.com/tarunspandit/codexflow/blob/main/FAQ.md">FAQ</a>
+          <a href="https://github.com/tarunspandit/codexflow/blob/main/SECURITY.md">Security notes</a>
+        </div>
+      </section>
+      <section id="faq" class="section">
+        <div class="section-heading">
+          <p class="eyebrow">FAQ</p>
+          <h2>The questions users will ask before installing.</h2>
+          <p>Short answers for account requirements, setup, URLs, safety, and what ChatGPT can actually access.</p>
+        </div>
+        <div class="faq-grid">
+          <article>
+            <h3>Which ChatGPT account should I use?</h3>
+            <p>Use a ChatGPT account with Apps / Developer Mode access. OpenAI lists Developer Mode for Pro, Plus, Business, Enterprise, and Education accounts on web. Current testing shows free and Go accounts do not expose the app flow needed for CodexFlow. A specific model surface may still be unable to call connectors; use Pro context fallback for those sessions.</p>
+          </article>
+          <article>
+            <h3>Does CodexFlow bypass rate limits?</h3>
+            <p>No. It does not bypass, avoid, increase, pool, resell, or modify ChatGPT, Codex, OpenAI, or third-party model limits. Every request still runs through your own ChatGPT session and whatever limits that account has.</p>
+          </article>
+          <article>
+            <h3>Why install globally?</h3>
+            <p>Global install gives users one command: <code>codexflow</code>. It avoids long <code>npx</code> commands and makes daily startup simply <code>codexflow</code>.</p>
+          </article>
+          <article>
+            <h3>What URL should I use?</h3>
+            <p>Use Cloudflare quick tunnel for demos. Use an ngrok free dev domain, Cloudflare named tunnel, or Tailscale Funnel when you want one ChatGPT app URL that survives restarts.</p>
+          </article>
+          <article>
+            <h3>Can ChatGPT see my Codex context?</h3>
+            <p>It can read explicit context files such as <code>AGENTS.md</code>, <code>.ai-bridge</code>, git status/diff, and selected source files. It cannot read hidden Codex runtime memory.</p>
+          </article>
+          <article>
+            <h3>Should CSP stay enabled?</h3>
+            <p>Yes. In Settings -> Security and login, turn on Developer mode and keep Enforce CSP in developer mode enabled. Create and manage the connection under Settings -> Plugins.</p>
+          </article>
+        </div>
+      </section>
+      <section id="stop" class="section two-col">
+        <div>
+          <p class="eyebrow">Start and stop</p>
+          <h2>Keep the terminal running while ChatGPT uses the connector.</h2>
+          <p>
+            CodexFlow owns the local MCP server and the tunnel process. Stop it when the session is over.
+          </p>
+        </div>
+        <div class="rules">
+          <div>
+            <strong>Start</strong>
+            <p>Run <code>codexflow</code> in the target repo. The Server URL is copied automatically.</p>
+          </div>
+          <div>
+            <strong>Open</strong>
+            <p>Press Enter in the terminal to open ChatGPT connector settings.</p>
+          </div>
+          <div>
+            <strong>End</strong>
+            <p>Press <code>q</code> or Ctrl+C. Quick tunnel URLs stop working. Stable hostnames stay reserved.</p>
+          </div>
+        </div>
+      </section>
+      <section class="section safety">
+        <div>
+          <p class="eyebrow">Safety boundary</p>
+          <h2>This is a local developer bridge, not an OS sandbox.</h2>
+        </div>
+        <ul>
+          <li>Public tunnels are token-protected by default.</li>
+          <li><code>.env</code>, private keys, <code>.git</code>, <code>node_modules</code>, and symlink escapes are blocked.</li>
+          <li>Safe bash allows common inspection and test commands, not arbitrary shell control.</li>
+          <li><code>--no-bash</code> disables all ChatGPT-triggered shell commands.</li>
+          <li><code>--bash-session</code> with <code>--require-bash-session</code> requires explicit session targeting before bash runs.</li>
+          <li>Use handoff mode when you want ChatGPT to plan and Codex to edit.</li>
+        </ul>
+      </section>
+    </main>
+    <footer class="site-footer">
+      <span>CodexFlow</span>
+      <a class="star-link" href="https://github.com/tarunspandit/codexflow"><img src="./star.svg" alt="" aria-hidden="true" />Star on GitHub</a>
+      <a href="https://www.npmjs.com/package/@tarunspandit/codexflow">npm</a>
+      <a href="./zh.html">中文</a>
+      <a href="https://github.com/tarunspandit/codexflow/blob/main/SECURITY.md">Security</a>
+    </footer>
+    <script src="./script.js?v=2"></script>
+  </body>
+</html>

package/docs/og.png ADDED Viewed

Binary file