[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-83996":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":15,"stars7d":16,"stars30d":16,"stars90d":14,"forks30d":14,"starsTrendScore":17,"compositeScore":18,"rankGlobal":9,"rankLanguage":9,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":20,"hasPages":20,"topics":22,"createdAt":9,"pushedAt":9,"updatedAt":23,"readmeContent":24,"aiSummary":9,"trendingCount":14,"starSnapshotCount":14,"syncStatus":13,"lastSyncTime":25,"discoverSource":26},83996,"codex-chatgpt-control","adamallcock\u002Fcodex-chatgpt-control","adamallcock","Unofficial SDK for Codex agents controlling visible ChatGPT web sessions",null,"JavaScript",201,15,2,0,10,63,83,3.61,"MIT License",false,"main",[],"2026-06-12 02:04:37","# codex-chatgpt-control\n\n[![CI](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Factions\u002Fworkflow\u002Fstatus\u002Fadamallcock\u002Fcodex-chatgpt-control\u002Fparity.yml?branch=main&label=CI&logo=github)](https:\u002F\u002Fgithub.com\u002Fadamallcock\u002Fcodex-chatgpt-control\u002Factions\u002Fworkflows\u002Fparity.yml)\n[![npm](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002Fcodex-chatgpt-control?logo=npm)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fcodex-chatgpt-control)\n[![PyPI](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fcodex-chatgpt-control?logo=pypi)](https:\u002F\u002Fpypi.org\u002Fproject\u002Fcodex-chatgpt-control\u002F)\n![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow)\n![Python](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FPython-3.10%2B-blue)\n![Node](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FNode-20%2B-green)\n\nUnofficial alpha SDK facade for Codex agents that need to run user-directed workflows in a visible ChatGPT web session.\n\nhttps:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F6ca38f2d-6646-490d-8e4d-8a6dc21e926f\n\n\n## Why This Exists\n\nThis project exists because Codex and ChatGPT are useful in different parts of the same work loop. Codex is the execution environment: it can read and edit the local repo, run commands, test changes, and prepare branches. ChatGPT, meanwhile, may expose different frontier models, Pro-tier reasoning modes, larger context windows, canvases, connectors, browsing\u002Fresearch tools, memory, or company knowledge at any given time.\n\nIn practice, that means a user can end up doing real work by hand across two surfaces:\n\n> I am flicking between Codex for execution, and ChatGPT with Pro for deep planning, information gathering, consensus building, branding, and research tasks.\n\n`codex-chatgpt-control` turns that manual tab switch into a structured, visible, user-directed bridge. It lets an agent stay inside Codex while asking ChatGPT web to help with the kinds of work where ChatGPT may currently be the stronger product surface: deep planning, long-context review, research synthesis, naming, positioning, brainstorming, design critique, and second-opinion analysis.\n\n- **Keep Codex as home base:** preserve the local execution loop while optionally consulting ChatGPT web for planning or research-heavy steps.\n- **Visible-session only:** drive chatgpt.com through a compatible Codex\u002Fbrowser bridge and user-visible UI controls, including file uploads and visible downloads where available.\n- **Workflow primitives, not a ChatGPT API:** support prompts, thread workflows, response capture, clear stop reasons, and privacy-preserving local reports without private endpoint access.\n- **Narrow by design:** built for Codex -> browser -> chatgpt.com workflows; it is not a generic browser automation framework, scraping tool, OpenAI API wrapper, or official OpenAI project.\n\nThis project is not affiliated with, endorsed by, or sponsored by OpenAI.\n\n## What This Is For\n\nUse `codex-chatgpt-control` when a Codex-style agent needs to work with the real ChatGPT web product that the user can see:\n\n- start or continue visible ChatGPT threads\n- submit prompts and read Markdown responses\n- attach approved local files through visible upload controls\n- download visible generated files\n- wait for and download image-only generated artifacts\n- tell the agent exactly why it could not continue when ChatGPT needs login, captcha, permissions, or UI review\n- save local run reports that omit prompt and response content by default\n\nThis project deliberately does not provide hidden ChatGPT access, account automation, or a replacement for the OpenAI API.\n\n-----\n\n## Install\n\nNode:\n\n```bash\nnpm install codex-chatgpt-control\n```\n\nPython:\n\n```bash\npython -m pip install codex-chatgpt-control\n```\n\nThe Node package is the browser-control runtime authority. The Python package is a parity client over the same local backend protocol.\n\n## Codex Desktop Setup\n\nThis repo includes a Codex plugin at [plugins\u002Fcodex-chatgpt-control](plugins\u002Fcodex-chatgpt-control). It is the easiest way to make Codex Desktop agents use this SDK consistently instead of hand-rolling browser commands.\n\nInstall the repository as a Codex plugin marketplace and add the plugin:\n\n```bash\ncodex plugin marketplace add adamallcock\u002Fcodex-chatgpt-control --ref main\ncodex plugin add codex-chatgpt-control@codex-chatgpt-control\n```\n\nWhen a new version ships, refresh the marketplace snapshot and reinstall the plugin, then start a new Codex thread so updated skill metadata is loaded:\n\n```bash\ncodex plugin marketplace upgrade codex-chatgpt-control\ncodex plugin add codex-chatgpt-control@codex-chatgpt-control\n```\n\nThe plugin contains:\n\n- `codex-chatgpt-control`: the broad visible ChatGPT web workflow and diagnostics skill.\n- `chatgpt-pro-consult`: a focused ChatGPT Pro second-opinion workflow.\n- bundled Node runtime files for bridge-enabled imports.\n\nManual skill-only install is still available as a fallback at [skills\u002Fcodex-chatgpt-control\u002FSKILL.md](skills\u002Fcodex-chatgpt-control\u002FSKILL.md):\n\n```bash\nmkdir -p ~\u002F.codex\u002Fskills\u002Fcodex-chatgpt-control\nrsync -a skills\u002Fcodex-chatgpt-control\u002F ~\u002F.codex\u002Fskills\u002Fcodex-chatgpt-control\u002F\n```\n\nThen add a short instruction to any repo where agents should be allowed to consult ChatGPT web:\n\n```markdown\nWhen a task would benefit from the visible ChatGPT web product, use the\ncodex-chatgpt-control skill and SDK. Keep the workflow visible and\nuser-directed. If I say a ChatGPT thread is already open, reuse that tab with\nexistingTab\u002Fexisting_tab instead of opening a replacement. If the browser bridge\nor ChatGPT UI is unavailable, report the SDK stop reason and do not retry\nblindly.\n```\n\nThe plugin and skill are agent-facing operating guides plus local runtime bundles. They do not bundle a browser bridge, credentials, or ChatGPT account access. Real browser workflows still require a compatible Codex\u002Fbrowser bridge and a visible signed-in ChatGPT web session.\n\n## Node Quick Start\n\nUse the SDK from a Codex\u002Fbrowser-bridge host that provides `globalThis.agent`:\n\n```ts\nimport { createChatGPT } from \"codex-chatgpt-control\";\n\nconst chatgpt = createChatGPT({ agent: globalThis.agent });\nconst reviewer = chatgpt.agent({\n  name: \"reviewer\",\n  instructions: \"Review carefully and return Markdown.\"\n});\n\nconst result = await chatgpt.runner.run(reviewer, {\n  input: \"Reply with a one-sentence summary of this project.\",\n  thread: { type: \"new\" },\n  response: { format: \"markdown\" }\n});\n\nconsole.log(result.output_text);\n```\n\nContinue a user-open ChatGPT thread without replacing the tab:\n\n```ts\nawait chatgpt.askInThread({\n  thread: { type: \"url\", url: \"https:\u002F\u002Fchatgpt.com\u002Fc\u002F\u003Cconversation-id>\" },\n  existingTab: true,\n  prompt: \"Continue from the latest answer.\",\n  wait: true,\n  read: { format: \"markdown\" }\n});\n```\n\nIf you run browser-required commands from an ordinary shell, the safe expected result is a structured `browser_bridge_unavailable` blocker. That means the protocol path is working, but no visible browser bridge was available to the process.\n\nDownload an image-only generation through the artifact primitives:\n\n```ts\nawait chatgpt.artifacts.wait({\n  kind: \"image\",\n  requireDownload: true\n});\n\nconst downloaded = await chatgpt.artifacts.downloadLatest({\n  destDir: \"\u002Fabsolute\u002Foutput\u002Fdir\"\n});\n```\n\nGenerated images are artifacts, not assistant text. `messages.readLatest()` can\ncorrectly return `not_found` for an image-only result while\n`artifacts.downloadLatest()` still saves the image. If a claimed user-open tab's\nbridge session is stale, artifact export may recover by reopening the same saved\n`https:\u002F\u002Fchatgpt.com\u002Fc\u002F...` conversation in a temporary bridge-owned tab and\nusing the bridge page-assets inventory. This recovery is fallback-only; normal\ntext\u002Fthread commands do not automatically replace the user's tab.\n\n## Python Quick Start\n\nThe Python package talks to the Node backend. Build or install a backend command first, then point Python at it:\n\n```bash\npython -m pip install codex-chatgpt-control\nnpm install codex-chatgpt-control\n```\n\n```python\nfrom codex_chatgpt_control import Agent, BackendClient, Runner, StdioBackendTransport\n\nbackend = BackendClient(StdioBackendTransport(\n    command=[\"npx\", \"--yes\", \"--package\", \"codex-chatgpt-control\", \"codex-chatgpt-control-backend\"]\n))\nrunner = Runner(backend)\n\ntry:\n    result = runner.run_sync(\n        Agent(name=\"reviewer\", instructions=\"Review carefully.\"),\n        {\n            \"input\": \"Reply with hi.\",\n            \"thread\": {\"type\": \"new\"},\n            \"response\": {\"format\": \"markdown\"},\n        },\n    )\nfinally:\n    backend.close()\n\nprint(result.status)\nprint(result.output_text)\n```\n\nThe Python package is a protocol client. The current browser runtime is still Node-backed.\n\n## Quick Start From Source\n\nClone the repo and build the Node runtime:\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fadamallcock\u002Fcodex-chatgpt-control.git\ncd codex-chatgpt-control\u002Fpackages\u002Fnode\nnpm ci\nnpm test\nnpm run build\nnpm run bundle\nnpm run bundle:backend\n```\n\nUse the built source bundle from a Codex\u002Fbrowser-bridge host:\n\n```ts\nimport { createChatGPT } from \".\u002Fdist\u002Fcodex-chatgpt-control.bundle.mjs\";\n\nconst chatgpt = createChatGPT({ agent: globalThis.agent });\n```\n\n-----\n\n![codex-chatgpt-control visible-session bridge banner](assets\u002Freadme\u002Fcodex-chatgpt-control-readme-banner.png)\n\n## SDK Shape\n\nThe main Node entrypoint is `createChatGPT({ agent })`. It exposes:\n\n- `chatgpt.agent(...)` and `chatgpt.runner.run(...)` for Agents-style visible-session workflows.\n- `chatgpt.ask(...)`, `askInThread(...)`, `askWithFiles(...)`, and `askAndDownload(...)` for common task flows.\n- `chatgpt.responses.create(...)` for a narrow Responses-shaped adapter over the same visible browser runner.\n- Primitive groups for `session`, `threads`, `messages`, `artifacts`, `files`, `modes`, `tools`, and `response`.\n- Discovery helpers: `chatgpt.help()`, `chatgpt.commands()`, and `chatgpt.describe(name)`.\n- Local run reports through `chatgpt.createReport(...)` and `chatgpt.reports`; prompt and response content is omitted unless explicitly enabled.\n\nUseful repo links:\n\n- [Bundled Codex skill](skills\u002Fcodex-chatgpt-control\u002FSKILL.md)\n- [Architecture](docs\u002Farchitecture.md)\n- [Browser bridge](docs\u002Fbrowser-bridge.md)\n- [Safety model](docs\u002Fsafety.md)\n- [Troubleshooting](docs\u002Ftroubleshooting.md)\n- [Release process](docs\u002Frelease-process.md)\n- [Python examples](packages\u002Fpython\u002Fexamples\u002F)\n\n## Runtime Requirements\n\nFor deterministic tests and ordinary-shell protocol checks:\n\n- Node.js 20 or newer for `packages\u002Fnode`\n- Python 3.10 or newer for `packages\u002Fpython`\n- npm for Node dependency installation\n- Python virtualenv tooling for Python development\n\nFor real ChatGPT browser control:\n\n- a signed-in ChatGPT web session in Chrome\n- a compatible Codex\u002Fbrowser bridge that exposes `globalThis.agent`\n- a visible browser tab or permission to open one\n- user approval for prompts, files, downloads, and any account-affecting action\n\n`globalThis.agent` is not created by this package. It must come from the host runtime, such as a Codex environment with a compatible browser bridge. The SDK refuses to fake this path: ordinary shell runs should return `browser_bridge_unavailable` for browser-required operations.\n\n### Local File Upload Requirements\n\nAttachment paths must be absolute on the machine running the Node backend. Use `\u002Fhome\u002Fyou\u002Ffile.pdf` or `\u002Fmnt\u002Fc\u002Fwork\u002Ffile.pdf` for Linux\u002FWSL backends. Use `C:\\Users\\you\\file.pdf` or `\\\\server\\share\\file.pdf` for Windows backends. The backend rejects ambiguous Windows forms such as `C:Users\\you\\file.pdf` and rejects Windows-looking paths when the backend host is POSIX.\n\nFile attachments need two separate permission gates:\n\n1. **Chrome extension gate:** open `chrome:\u002F\u002Fextensions`, choose the Codex\u002Fbrowser bridge extension, open **Details**, and enable **Allow access to file URLs**.\n2. **Codex app gate:** in Codex settings, allow Google Chrome uploads under **Computer Use > Google Chrome > Permissions > Uploads**. Choose the most restrictive setting that still fits your workflow; for unattended local smoke tests, use the setting that always allows uploads.\n\nIf either gate is missing, file upload workflows should stop with a structured permission blocker instead of retrying blindly.\n\n## Repository Layout\n\n```text\nskills\u002F             Public Codex skill for agent-facing usage\npackages\u002Fnode\u002F      TypeScript runtime, contracts, backend server, tests\npackages\u002Fpython\u002F    Python parity client, examples, tests\ndocs\u002F               Public architecture, safety, bridge, and release notes\n.github\u002Fworkflows\u002F  Deterministic CI gates\n```\n\n-----\n\n## Development\n\nRun deterministic Node gates:\n\n```bash\ncd packages\u002Fnode\nnpm ci\nnpm test\nnpm run build\nnpm run bundle\nnpm run bundle:backend\nnpm run contract:validate\nnpm run parity:fixtures\n```\n\nRun deterministic Python gates after the backend bundle exists:\n\n```bash\ncd packages\u002Fpython\npython -m pip install -e .[dev]\npython -m unittest discover -s tests\npython -m compileall -q src examples\npython -m pyright src tests\npython scripts\u002Flive_smoke.py --mode ordinary-shell\n```\n\nOrdinary-shell smoke checks are expected to return structured browser-bridge blockers for browser-required actions. A real ChatGPT run requires a compatible visible browser session and bridge.\n\n## Package Coordinates\n\n- npm package: [`codex-chatgpt-control`](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fcodex-chatgpt-control)\n- PyPI package: [`codex-chatgpt-control`](https:\u002F\u002Fpypi.org\u002Fproject\u002Fcodex-chatgpt-control\u002F)\n- Node import: `import { createChatGPT } from \"codex-chatgpt-control\";`\n- Python import: `import codex_chatgpt_control`\n\n## Safety\n\nDo not use this project to bypass login, access hidden endpoints, scrape private data, or automate activity outside a user-directed visible session. See [docs\u002Fsafety.md](docs\u002Fsafety.md) and [SECURITY.md](SECURITY.md).\n","2026-06-11 04:12:01","CREATED_QUERY"]