@youdie006/prodex 0.39.0 → 0.39.2
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.
- package/README.md +161 -521
- package/dist/chatgpt-browser.js +494 -49
- package/dist/cli-help.js +10 -10
- package/dist/cli-pro.js +50 -7
- package/dist/cli-server.js +33 -1
- package/dist/mcp.js +1 -1
- package/dist/picker-interaction.js +112 -0
- package/docs/cli-reference.md +380 -0
- package/docs/releasing.md +83 -0
- package/package.json +3 -1
package/README.md
CHANGED
|
@@ -1,616 +1,256 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
|
|
3
|
-
<
|
|
3
|
+
<picture>
|
|
4
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/youdie006/prodex/main/assets/logo-wordmark-dark.png">
|
|
5
|
+
<img src="https://raw.githubusercontent.com/youdie006/prodex/main/assets/logo-wordmark.png" width="300" alt="PROdex">
|
|
6
|
+
</picture>
|
|
4
7
|
|
|
5
|
-
**
|
|
8
|
+
**Ask ChatGPT Pro from your terminal, or let Codex, Claude and other coding agents ask it for you, through the logged-in browser you already have, with a receipt for every answer.**
|
|
6
9
|
|
|
7
|
-
[](LICENSE)
|
|
8
|
-
[](package.json)
|
|
9
10
|
[](https://github.com/youdie006/prodex/actions/workflows/ci.yml)
|
|
10
|
-
[](https://www.npmjs.com/package/@youdie006/prodex)
|
|
12
|
+
[](package.json)
|
|
13
|
+
[](LICENSE)
|
|
14
|
+
[](#what-it-will-not-do)
|
|
11
15
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
---
|
|
15
|
-
|
|
16
|
-
`prodex` is a local receipt bus plus MCP bridge for coordinating Codex execution with ChatGPT Pro/Projects and Claude.
|
|
17
|
-
|
|
18
|
-
The goal is not to turn ChatGPT Pro into a public API. The goal is to make Codex the main workbench while keeping durable receipts for every outside consult or handoff:
|
|
19
|
-
|
|
20
|
-
- Ask ChatGPT Pro from Codex when a stronger planning/review pass is useful.
|
|
21
|
-
- Let ChatGPT Projects hand structured tasks to Codex/local tools through an optional HTTP MCP bridge.
|
|
22
|
-
- Let Claude create/fetch the same tasks through stdio MCP.
|
|
23
|
-
- Keep durable records of what was asked, what was returned, and what Codex did with it.
|
|
24
|
-
|
|
25
|
-
## Quickstart: a Pro second opinion from your terminal
|
|
16
|
+
[Install](#install) · [Quick start](#quick-start) · [Agents over MCP](#agents-over-mcp) · [Model, effort, project](#model-effort-and-project) · [No window](#running-without-a-window) · [Receipts](#receipts) · [FAQ](#faq)
|
|
26
17
|
|
|
27
|
-
|
|
18
|
+
<img src="https://raw.githubusercontent.com/youdie006/prodex/main/docs/demo-cli.webp" width="780" alt="Terminal recording: prodex ask sends a question to ChatGPT Pro, prints progress while Pro reasons for two and a half minutes, prints the answer and where it was saved; pro latest re-prints it; pro browser models reads the picker's five rungs ending in Pro; claude config prints the MCP config for an agent">
|
|
28
19
|
|
|
29
|
-
|
|
30
|
-
npm install -g @youdie006/prodex # needs Node 20+, git, ripgrep
|
|
31
|
-
|
|
32
|
-
prodex pro browser login # opens a dedicated Chrome and waits until your ChatGPT login is READY
|
|
33
|
-
prodex ask --file src/auth.ts "Review this for security holes"
|
|
34
|
-
```
|
|
20
|
+
</div>
|
|
35
21
|
|
|
36
|
-
|
|
22
|
+
You pay for ChatGPT Pro. The reasoning that makes it worth paying for lives behind a web page, and the coding agent you actually spend the day with cannot reach it. prodex closes that gap without an API key, a proxy, or a stealth bot: it drives a real, visible Chrome that you logged into once, types into the same composer you would, and reads the answer back from the conversation transcript.
|
|
37
23
|
|
|
38
|
-
|
|
24
|
+
```console
|
|
25
|
+
$ prodex ask --new-chat --effort Pro "A CLI drives a logged-in browser over the Chrome DevTools Protocol and holds a cross-process file lock while a send is in flight. What failure modes must the lock's expiry rule handle, and which single rule would you ship? Under 150 words."
|
|
26
|
+
progress: connecting to browser (port 9333)
|
|
27
|
+
progress: applying selection (effort=Pro project=set)
|
|
28
|
+
progress: prompt sent, waiting for answer (budget 20 min)
|
|
29
|
+
progress: waiting 1m 21s (generating)
|
|
30
|
+
progress: answer received after 2m 32s (transcript (1235 chars))
|
|
31
|
+
model_used: gpt-6-pro
|
|
39
32
|
|
|
40
|
-
|
|
33
|
+
Handle slow legitimate sends, hung or suspended owners, sleep/reboot, clock jumps,
|
|
34
|
+
crashes leaving stale files, PID reuse, incomplete metadata, competing reclaimers,
|
|
35
|
+
...
|
|
36
|
+
I'd ship: reclaim only a provably dead original owner's lock - never expire a live
|
|
37
|
+
or unverifiable owner by age.
|
|
41
38
|
|
|
42
|
-
|
|
43
|
-
Codex
|
|
44
|
-
| pro ask preview / tasks / mcp
|
|
45
|
-
v
|
|
46
|
-
prodex local bridge + .bridge receipts
|
|
47
|
-
| ^
|
|
48
|
-
| optional explicit | optional HTTP/stdin MCP
|
|
49
|
-
| pro browser consult |
|
|
50
|
-
v |
|
|
51
|
-
ChatGPT Pro ChatGPT Projects / Claude
|
|
39
|
+
saved: .bridge/artifacts/pro-consults/task_20260908_032750_gpt-pro-consult.md
|
|
52
40
|
```
|
|
53
41
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
- Manual-first: each ChatGPT Pro consult should be user-initiated or clearly tied to the current task.
|
|
57
|
-
- Browser automation is optional and explicit: use it only through `pro browser ...`, with a real visible logged-in browser session.
|
|
58
|
-
- Stop on blockers: login, captcha, rate limit, Cloudflare, permission, and model-limit states stop the workflow.
|
|
59
|
-
- No bypass: no hidden API, cookie extraction, stealth automation, proxies, or captcha solving.
|
|
60
|
-
- Low volume: no batch prompting or recurring loops that make ChatGPT Pro behave like an API server. Visible-browser sends are auto-throttled to human pace (one every 10s by default; tune with `PRODEX_MIN_SEND_INTERVAL_MS`, `0` to disable).
|
|
61
|
-
- Local only: do not expose account access, browser sessions, or bridge endpoints to other users.
|
|
62
|
-
- Local debug port: the visible-browser adapter uses Chrome's `--remote-debugging-port`, which is unauthenticated but bound to `127.0.0.1` only and live only while that browser is open.
|
|
63
|
-
|
|
64
|
-
## Components
|
|
65
|
-
|
|
66
|
-
- `docs/clients.md`: connect Cursor, Gemini CLI, Codex, Claude, and other MCP agents to the ChatGPT Pro bridge.
|
|
67
|
-
- `docs/http-mcp.md`: ChatGPT Project HTTP MCP setup and safety notes.
|
|
68
|
-
- `docs/claude.md`: Claude stdio MCP setup and tool notes.
|
|
69
|
-
- `.bridge/`: local task/result/session/artifact/receipt storage.
|
|
70
|
-
|
|
71
|
-
## Works with
|
|
72
|
-
|
|
73
|
-
Two sibling local-first tools by the same author understand prodex's on-disk
|
|
74
|
-
ledger (prodex >=0.11.0 registers every bridge root in
|
|
75
|
-
`~/.local/share/prodex/bridges.json` so they can find it):
|
|
76
|
-
|
|
77
|
-
- [sessionwiki](https://github.com/youdie006/sessionwiki) (>=0.19.0) indexes
|
|
78
|
-
every consult as a searchable session - the task is the question, the
|
|
79
|
-
answer artifact is the answer. "What did GPT Pro say about the retry loop
|
|
80
|
-
last week?" is `sessionwiki search "retry"`, and `sessionwiki resume <id>`
|
|
81
|
-
prints the ChatGPT thread the consult ran in.
|
|
82
|
-
- [swapdex](https://github.com/youdie006/swapdex) switches Claude Code / Codex
|
|
83
|
-
login accounts; its `ui` lists recent sessions (including consults, via
|
|
84
|
-
sessionwiki) after every switch.
|
|
85
|
-
|
|
86
|
-
Nothing changes if they are not installed - the registry is advisory, holds
|
|
87
|
-
paths only, and a registry failure never breaks a bridge operation.
|
|
88
|
-
|
|
89
|
-
## Package Surface
|
|
90
|
-
|
|
91
|
-
The npm package is CLI-only for now. The supported public surfaces are the `prodex` command, the stdio MCP server, and the optional HTTP MCP server. JavaScript imports from `prodex` or `prodex/dist/*` are intentionally not exported until a library API is designed and documented.
|
|
92
|
-
|
|
93
|
-
## Status
|
|
94
|
-
|
|
95
|
-
Implemented:
|
|
42
|
+
That is a real run, timings included. Every consult lands as a task, a result and an HMAC-signed receipt under `.bridge/` in your repo, so `prodex pro latest` re-prints it, your agent can fetch it over MCP, and a week later you can still answer "what did Pro say about the lock?".
|
|
96
43
|
|
|
97
|
-
|
|
98
|
-
- CLI commands for task creation/listing/inspection/claiming/completion/blocking and result display.
|
|
99
|
-
- `pro ask` and `pro latest` for Codex-first consult previews and review receipts.
|
|
100
|
-
- `sessions list` and `sessions show` for inspecting dry-run, running, done, or blocked consult sessions.
|
|
101
|
-
- `receipts list` and `receipts show` for inspecting the local action ledger without exposing legacy inline write payloads.
|
|
102
|
-
- Ledger MCP tools for creating, claiming, completing, blocking, and inspecting task/result/session/receipt records from Claude or ChatGPT Projects.
|
|
103
|
-
- Read-only result artifact fetch for Pro consult and generic MCP handoff artifacts explicitly listed on result records.
|
|
104
|
-
- Explicit local reseal for legacy signed result receipts after reviewing the current result payload.
|
|
105
|
-
- `pro browser login/check/smoke/ask` for the optional visible browser adapter.
|
|
106
|
-
- Claude-compatible stdio MCP server through `prodex mcp`.
|
|
107
|
-
- ChatGPT Developer Mode-style Streamable HTTP MCP server through `prodex setup` and `prodex start`.
|
|
108
|
-
- Read-only repo tools for bounded file reads and ripgrep search.
|
|
109
|
-
- Receipt-gated repo write/stage tools for existing text files: dry-run first, apply only with matching git HEAD and preimage hash, then stage only reviewed applied receipts.
|
|
110
|
-
- `doctor` local health check for `.bridge`, redacted config loading, receipt-backed write/apply/stage, and the real HTTP MCP tool catalog.
|
|
44
|
+
## What you can do with it
|
|
111
45
|
|
|
112
|
-
|
|
46
|
+
- **Ask from the terminal.** `prodex ask` with a question, a file's contents (`--file`), an uploaded pdf, deck, sheet or image (`--attach`), or anything piped in (`--stdin`). Deep research, web search and image creation are one flag away (`--tool`).
|
|
47
|
+
- **Let your agent ask.** `prodex mcp` is a stdio MCP server with a `pro_consult` tool; Claude Code, Codex, Cursor and Gemini CLI call it like any other tool. ChatGPT Projects can hand work back the other way over a loopback HTTP MCP bridge.
|
|
48
|
+
- **Pick the model and effort per ask.** The picker ChatGPT shows is the picker prodex drives: `--effort Pro` reaches the top rung, `--project` sends inside a sidebar project, and `prodex setup` pins defaults per repo.
|
|
49
|
+
- **Keep every answer.** Tasks, results, sessions and receipts are versioned JSON on disk, signed with a local key. Nothing is stored anywhere else.
|
|
50
|
+
- **Run it with no window at all.** One headed login, then a virtual display: a real browser that Cloudflare treats as one, and nothing on your desktop.
|
|
51
|
+
- **Stop where a person should.** Login, captcha, Cloudflare, usage limits and permission prompts halt the send with a named blocker and a next step. prodex solves none of them for you.
|
|
113
52
|
|
|
114
|
-
|
|
115
|
-
- Cookie, token, localStorage, or sessionStorage extraction.
|
|
116
|
-
- Direct ungated write tools.
|
|
117
|
-
- Shell execution tools.
|
|
118
|
-
- Automatic public tunnel setup.
|
|
53
|
+
## Install
|
|
119
54
|
|
|
120
|
-
|
|
55
|
+
Node 20 or newer, `git`, and `ripgrep` (`rg`) on PATH. A Chromium-family browser for the visible adapter: Chrome, Chromium, Edge or Brave on PATH, in the standard macOS and Windows locations, or on the Windows host under WSL are all found automatically; anything else via `PRODEX_CHROME=/path/to/browser`.
|
|
121
56
|
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
Requires Node.js 20 or newer, `git`, and `ripgrep` (`rg`) on PATH. The optional visible-browser adapter needs a Chromium-family browser: PATH binaries (`google-chrome`, `chromium`, `chromium-browser`, `microsoft-edge`, `brave-browser`), standard macOS app bundles, Windows Program Files/LOCALAPPDATA installs, and Windows-host browsers under WSL are all probed automatically; anything else via `PRODEX_CHROME=/path/to/browser`.
|
|
125
|
-
|
|
126
|
-
Install from npm — **note the scope**. The unscoped `prodex` on npm is an unrelated third-party package; do **not** install it. Use the scoped name:
|
|
127
|
-
|
|
128
|
-
```bash
|
|
57
|
+
```sh
|
|
129
58
|
npm install -g @youdie006/prodex
|
|
130
59
|
```
|
|
131
60
|
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
```bash
|
|
135
|
-
prodex onboard
|
|
136
|
-
prodex init
|
|
137
|
-
prodex doctor
|
|
138
|
-
prodex pro ask --cwd /absolute/path/to/your/repo "Review the project positioning"
|
|
139
|
-
```
|
|
140
|
-
|
|
141
|
-
For a source checkout:
|
|
142
|
-
|
|
143
|
-
```bash
|
|
144
|
-
cd /absolute/path/to/prodex
|
|
145
|
-
npm install
|
|
146
|
-
npm run build
|
|
147
|
-
SOURCE_CLI="/absolute/path/to/prodex/dist/cli.js"
|
|
148
|
-
node "$SOURCE_CLI" onboard --source-cli "$SOURCE_CLI"
|
|
149
|
-
node "$SOURCE_CLI" init
|
|
150
|
-
node "$SOURCE_CLI" doctor --source-cli "$SOURCE_CLI"
|
|
151
|
-
node "$SOURCE_CLI" pro ask --cwd /absolute/path/to/your/repo "Review the project positioning"
|
|
152
|
-
```
|
|
153
|
-
|
|
154
|
-
The examples below use the installed `prodex` binary. In a source checkout, replace `prodex` with `node /absolute/path/to/prodex/dist/cli.js` after building, and pass `--source-cli /absolute/path/to/prodex/dist/cli.js` to onboarding, browser, prompt, and local MCP troubleshooting commands so their follow-up guidance stays in source-checkout form.
|
|
155
|
-
`onboard` prints the Claude, ChatGPT Project, and optional ChatGPT Pro consult commands without changing local state.
|
|
156
|
-
|
|
157
|
-
`init` creates the local `.bridge/` ledger directories and ignore rules. On a source checkout it may also add `node_modules/` and `dist/` to the repo root `.gitignore` so local dependencies and build output stay out of git.
|
|
158
|
-
Run `init` from the repo root, or use `prodex init --cwd /absolute/path/to/your/repo` from elsewhere.
|
|
159
|
-
|
|
160
|
-
`pro ask` is a dry-run/manual preview. It does not drive a logged-in browser; `pro ask --send` is rejected so accidental sends do not happen through the preview alias. Use `pro browser ask` when you explicitly want the visible browser adapter.
|
|
161
|
-
Run `pro ask` and `pro browser ask` from the repo root, or pass `--cwd /absolute/path/to/your/repo` so `--file` paths and `.bridge` records resolve to the intended project. If you generated commands with `onboard --cwd`, those commands already include the target cwd.
|
|
162
|
-
Bridge inspection and task handoff commands such as `pro browser check`, `pro latest`, `pro show`, `tasks create/list/show/claim/complete/block`, `results show`, `results artifact`, `receipts show`, and `sessions show` can also be run from elsewhere with `--cwd /absolute/path/to/your/repo`.
|
|
163
|
-
When the file exists and you want it included, add it explicitly, for example `prodex pro ask --cwd /absolute/path/to/your/repo --file README.md "Review the project positioning"`.
|
|
164
|
-
If your prompt itself starts with flag-like text, put `--` before the prompt. This applies to both preview and visible-browser sends, for example `prodex pro ask -- --strict mode review` or `prodex pro browser ask -- --strict mode review`.
|
|
165
|
-
|
|
166
|
-
## First Pro Login
|
|
167
|
-
|
|
168
|
-
Use this only when you explicitly want to use your logged-in ChatGPT Pro web session.
|
|
169
|
-
|
|
170
|
-
```bash
|
|
171
|
-
prodex pro browser login --dry-run
|
|
172
|
-
prodex pro browser login
|
|
173
|
-
prodex pro browser help
|
|
174
|
-
prodex pro browser check
|
|
175
|
-
prodex pro browser smoke --cwd /absolute/path/to/your/repo
|
|
176
|
-
```
|
|
177
|
-
|
|
178
|
-
If you use a non-default debug port or Chrome profile, pass it to `login`; the printed follow-up `check` and `smoke` commands keep the matching `--port`. To stop repeating `--port` on every command, export `PRODEX_CDP_PORT=<port>` once — explicit `--port` still wins. If you launch from outside the repo you want to inspect, pass `--cwd /absolute/path/to/your/repo` to `login`, `check`, or `smoke` so the command targets the same bridge. On slower first launches, add `--launch-timeout-ms 12000`.
|
|
179
|
-
|
|
180
|
-
For a source checkout, keep the follow-up commands in source-checkout form too:
|
|
181
|
-
|
|
182
|
-
```bash
|
|
183
|
-
cd /absolute/path/to/prodex
|
|
184
|
-
SOURCE_CLI="/absolute/path/to/prodex/dist/cli.js"
|
|
185
|
-
node "$SOURCE_CLI" pro browser login --dry-run --source-cli "$SOURCE_CLI"
|
|
186
|
-
node "$SOURCE_CLI" pro browser login --source-cli "$SOURCE_CLI"
|
|
187
|
-
node "$SOURCE_CLI" pro browser help --source-cli "$SOURCE_CLI"
|
|
188
|
-
node "$SOURCE_CLI" pro browser check --source-cli "$SOURCE_CLI"
|
|
189
|
-
node "$SOURCE_CLI" pro browser smoke --source-cli "$SOURCE_CLI" --cwd /absolute/path/to/your/repo
|
|
190
|
-
```
|
|
61
|
+
Note the scope: the unscoped `prodex` on npm is an unrelated package.
|
|
191
62
|
|
|
192
|
-
|
|
63
|
+
## Quick start
|
|
193
64
|
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
- Pick the Pro/Thinking model you want in the ChatGPT UI.
|
|
201
|
-
- The login stays in the dedicated profile:
|
|
202
|
-
|
|
203
|
-
```text
|
|
204
|
-
~/.local/share/prodex/chrome-chatgpt-pro
|
|
205
|
-
```
|
|
206
|
-
|
|
207
|
-
You can close that Chrome window after check/smoke or when you are done. The next time you need it, run `pro browser login` or `pro browser check` again. `check` will tell you what to do if the browser is closed.
|
|
208
|
-
|
|
209
|
-
Actual explicit visible-browser consult (`prodex ask` is the short form of `prodex pro browser ask`):
|
|
210
|
-
|
|
211
|
-
```bash
|
|
212
|
-
cd /absolute/path/to/your/repo
|
|
213
|
-
prodex ask --file README.md "Review the project positioning"
|
|
214
|
-
prodex pro latest
|
|
215
|
-
prodex results show latest
|
|
216
|
-
prodex results artifact latest
|
|
217
|
-
prodex sessions show latest
|
|
218
|
-
```
|
|
219
|
-
|
|
220
|
-
This uses the currently available ChatGPT web session and model selection. It is not a hidden API client, and it does not read cookies, tokens, localStorage, or sessionStorage.
|
|
221
|
-
|
|
222
|
-
#### Choosing the model, reasoning effort, and project
|
|
223
|
-
|
|
224
|
-
The visible-browser send drives the same composer picker you use by hand, so you can pick the model, reasoning effort, or a sidebar project per ask:
|
|
225
|
-
|
|
226
|
-
```bash
|
|
227
|
-
# Pro extended sub-mode, inside an existing sidebar project
|
|
228
|
-
prodex pro browser ask --model Pro --project "my-project" "Review the migration plan"
|
|
229
|
-
|
|
230
|
-
# A non-Pro model at a specific reasoning effort
|
|
231
|
-
prodex pro browser ask --effort "매우 높음" "Draft the release notes"
|
|
232
|
-
```
|
|
233
|
-
|
|
234
|
-
Selection matches menu items by their visible text and is verified in both the **Korean** (즉시/중간/높음/매우 높음, Pro 기본/확장) and the **English (US)** ChatGPT UI (Instant/Medium/High/Extra High, Pro Standard/Extended) — every canonical flag value matches either locale's labels automatically. For other display languages, use the escape hatch: `--model "<exact label>"` clicks any radio entry in the picker by the exact text your UI shows (run `pro browser models` to list them).
|
|
235
|
-
|
|
236
|
-
To see the labels your account currently shows, list them read-only (opens the menu, reads it, presses Escape — nothing is selected):
|
|
237
|
-
|
|
238
|
-
```bash
|
|
239
|
-
prodex pro browser models
|
|
240
|
-
```
|
|
241
|
-
|
|
242
|
-
- `--model` picks the composer model by its exact menu label. `Pro` is verified end-to-end. Models whose menu entry opens a submenu of variants (for example GPT-5.5) are rejected with a clear error instead of silently keeping the previous model; direct variant selection is planned.
|
|
243
|
-
- `--pro-mode 기본|확장` selects the Pro sub-mode where the ChatGPT picker exposes one: sub-modes belong to the GPT-5.5 generation ("Pro Standard/Extended use GPT-5.5 Pro" per OpenAI docs), so with the GPT-5.6 generation selected the picker shows a single Pro and this flag fails with guidance. Any effective Pro selection (`--model Pro` or a sub-mode) raises the default `--timeout-ms` to 1200000 - Pro reasoning routinely runs for many minutes (an explicit `--timeout-ms` always wins).
|
|
244
|
-
- `--effort 즉시|중간|높음|"매우 높음"` sets the reasoning effort. English aliases `instant`/`medium`/`high`/`max` are accepted. The effort options and Pro share one radio group in ChatGPT, so picking an effort switches the composer to the standard reasoning model and deselects Pro; for the same reason `--pro-mode` and `--effort` cannot be combined.
|
|
245
|
-
- `--project "name"` enters an existing sidebar project before sending. `--project-new "name"` creates a new project (sidebar 새 프로젝트 popover, committed with Enter) and sends inside it. Neither can be combined with `--target-url` (the project step would navigate away from the confirmed tab), and `--project-new` never comes from saved defaults — creating a project is always an explicit per-ask choice.
|
|
246
|
-
|
|
247
|
-
Selection clicks are guarded: prodex refuses to click a control that is covered or out of view, waits for the menu to actually open instead of sleeping a fixed delay, and treats a menu that stays open after a pick as a failed selection. If any step fails, it backs out with Escape and reports a blocker instead of sending with the wrong model. Note that an applied selection stays active in your ChatGPT session after the send — switch back manually if you were on a different model.
|
|
248
|
-
|
|
249
|
-
Persist defaults so you can omit these flags on routine asks; a per-ask flag always overrides the saved default. View saved defaults with `prodex status`, clear one with the matching `--clear-*` flag, or answer a short wizard instead of remembering flags:
|
|
250
|
-
|
|
251
|
-
```bash
|
|
252
|
-
prodex setup --model Pro --project "my-project"
|
|
253
|
-
prodex setup --clear-project
|
|
254
|
-
prodex setup --interactive # asks model / Pro sub-mode or effort / project
|
|
255
|
-
```
|
|
256
|
-
|
|
257
|
-
The saved default above lives in the repo's `.bridge/config.local.json`, so it only applies when `prodex` runs from that repo. A coding agent often starts the MCP as `prodex mcp` with no `--cwd` (it reads whatever directory the agent launched in), so a per-repo default is missed and consults land in the general chat. For a default that applies from **any** directory, set environment variables instead — `PRODEX_DEFAULT_PROJECT` and `PRODEX_DEFAULT_MODEL` (also `PRODEX_DEFAULT_PRO_MODE`, `PRODEX_DEFAULT_EFFORT`) — in the agent's MCP `env` block or your shell. Use your own project name (list them with `prodex pro browser projects`); with no project set, consults simply go to the general chat. A per-repo config still wins field-by-field over the env fallback.
|
|
258
|
-
|
|
259
|
-
### No window at all: virtual display (recommended)
|
|
260
|
-
|
|
261
|
-
Log in once, then never see the browser again:
|
|
262
|
-
|
|
263
|
-
```bash
|
|
264
|
-
prodex pro browser login # once, headed - sign in
|
|
265
|
-
prodex pro browser login --virtual-display # from now on: no window anywhere
|
|
65
|
+
```sh
|
|
66
|
+
prodex pro browser login # opens a dedicated Chrome; sign in once, it waits until READY
|
|
67
|
+
prodex ask "Explain this stack trace"
|
|
68
|
+
prodex ask --file src/auth.ts "Review this for security holes"
|
|
69
|
+
git diff | prodex ask --stdin "Review this diff"
|
|
70
|
+
prodex pro latest # re-print the last answer
|
|
266
71
|
```
|
|
267
72
|
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
Requires `Xvfb` and `xauth` (`sudo apt install -y xvfb x11-xkb-utils xauth`); prodex names the package if they are missing. Linux and WSL only. The display is served over loopback TCP because WSLg mounts `/tmp/.X11-unix` read-only, and it is protected by a per-display xauth cookie under `~/.local/share/prodex/xvfb/` — never `-ac`, so no other process can watch your signed-in window. The X server outlives the CLI on purpose (the browser runs on it) and is reused by later commands; `PRODEX_VIRTUAL_DISPLAY_NUM` picks the display number if `:99` is taken.
|
|
271
|
-
|
|
272
|
-
A browser already running on your desktop cannot be moved onto a virtual display by reusing it, so prodex refuses the switch and tells you to close it first (`pkill -f "remote-debugging-port=9333"`).
|
|
273
|
-
|
|
274
|
-
### Keeping the window, just out of the way
|
|
275
|
-
|
|
276
|
-
`prodex pro browser login --minimized` (or `PRODEX_MINIMIZE_WINDOW=1`) launches the dedicated browser and then minimizes it. It stays a **real headed Chrome** — which is the point, because Cloudflare admits headed browsers and rejects headless ones — but nothing sits on your desktop.
|
|
73
|
+
`prodex ask` is the short form of `prodex pro browser ask`; every flag works on both. The login opens its own Chrome profile (`~/.local/share/prodex/chrome-chatgpt-pro`), never your daily browser, and in a terminal it keeps watching the window and names the manual step still missing (sign in, clear a check, open a chat) until it reports READY.
|
|
277
74
|
|
|
278
|
-
|
|
75
|
+
While Pro thinks, progress goes to stderr: connecting, prompt sent, elapsed time while generating. A Pro selection raises the send budget to twenty minutes on its own; `--timeout-ms` overrides it. The answer is read from the conversation transcript rather than scraped off the page, so tables and fenced code arrive intact and citations keep their links. If the dedicated browser is not running, an interactive `ask` starts it, waits for your saved session, and retries once (`--no-auto-login` turns that off; scripts opt in with `--auto-login`).
|
|
279
76
|
|
|
280
|
-
|
|
77
|
+
Useful flags on every send:
|
|
281
78
|
|
|
282
|
-
|
|
79
|
+
| Flag | What it does |
|
|
80
|
+
|---|---|
|
|
81
|
+
| `--new-chat` | Send into a fresh chat. Recommended for repeated consults; very long threads eventually confuse send detection. |
|
|
82
|
+
| `--file path` | Inline a text file's contents into the prompt. Repeatable. |
|
|
83
|
+
| `--attach path` | Upload the file itself: the only way to hand ChatGPT a pdf, pptx, xlsx or image. Paths must live inside the repo. |
|
|
84
|
+
| `--tool deep-research` | Run a browsed report; the budget rises to thirty minutes and the full report comes back through the transcript. Also `web-search`, `create-image`, or any label the menu shows. |
|
|
85
|
+
| `--project "name"` | Send inside an existing sidebar project. `--project-new` creates one first. `prodex pro browser projects` lists exact names. |
|
|
86
|
+
| `--temporary` | A ChatGPT Temporary Chat: nothing in your chat list, but the answer is read off the page and cannot be recovered later. |
|
|
87
|
+
| `--json` | Structured output on stdout, progress on stderr. |
|
|
88
|
+
| `--target-url url --confirm-target` | Send into a specific thread the dedicated browser already has open. |
|
|
283
89
|
|
|
284
|
-
|
|
285
|
-
- **One mode at a time.** A single Chrome profile cannot serve a headed and a headless instance simultaneously; close the running one before switching (prodex refuses the switch instead of silently reusing the wrong mode).
|
|
90
|
+
Prefer prompts to flags? `prodex ui` (or a bare `prodex` in a terminal) asks what to send and where, shows a progress bar, and prints the equivalent command so the flags are learnable.
|
|
286
91
|
|
|
287
|
-
|
|
92
|
+
## Agents over MCP
|
|
288
93
|
|
|
289
|
-
|
|
94
|
+
**Claude Code, Codex, Cursor, Gemini CLI** talk to prodex over stdio. For Claude:
|
|
290
95
|
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
For a source checkout, keep the explicit send and inspection commands source-aware too:
|
|
294
|
-
|
|
295
|
-
```bash
|
|
296
|
-
cd /absolute/path/to/prodex
|
|
297
|
-
SOURCE_CLI="/absolute/path/to/prodex/dist/cli.js"
|
|
298
|
-
node "$SOURCE_CLI" pro browser ask --source-cli "$SOURCE_CLI" --cwd /absolute/path/to/your/repo --file README.md "Review the project positioning"
|
|
299
|
-
node "$SOURCE_CLI" pro latest --source-cli "$SOURCE_CLI"
|
|
300
|
-
```
|
|
301
|
-
|
|
302
|
-
Pass `--source-cli /absolute/path/to/prodex/dist/cli.js` to `pro browser ask`, `pro list`, `pro latest`, or `pro show <task-id|latest>` so blocked consults display source-checkout retry commands instead of installed-binary commands.
|
|
303
|
-
|
|
304
|
-
Each explicit browser consult creates a `.bridge` task and `.bridge/sessions` record before sending. If the visible browser is blocked by login, captcha, permission, or usage limits, the task is completed as a blocked consult so `prodex pro latest` still shows what happened, including the blocker code and next step; the failed command also prints the recorded task id plus `pro show`/`pro latest` inspection commands. Successful answers are normally saved as result artifacts under `.bridge/artifacts/pro-consults/` before the task result is finalized; if artifact or receipt recording fails after an answer is received, the answer is still completed as the result summary with a warning, and fatal finalization failures print the received answer before exiting. If a Pro answer is too large for `bridge_fetch_result_artifact`, it stays in the result summary with `answer_artifact_warning` and no unfetchable artifact is listed. Generic MCP handoff result artifacts can be stored under `.bridge/artifacts/results/`; `bridge_fetch_result_artifact` only reads artifacts explicitly listed on the result record, and newly finalized result artifacts are checked against the sha256 recorded at finalization time.
|
|
305
|
-
|
|
306
|
-
If an older local result is reported as untrusted because a locally signed legacy `task_completed` receipt is missing `result_sha256`, review `.bridge/results/<task-id>.json` yourself first, then run:
|
|
307
|
-
|
|
308
|
-
```bash
|
|
309
|
-
prodex results reseal <task-id> --confirm-current-result
|
|
96
|
+
```sh
|
|
97
|
+
prodex claude config --cwd /absolute/path/to/your/repo
|
|
310
98
|
```
|
|
311
99
|
|
|
312
|
-
|
|
100
|
+
prints a token-free config that points Claude at `prodex mcp --cwd /absolute/path/to/your/repo`:
|
|
313
101
|
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
```bash
|
|
317
|
-
prodex receipts rotate-key
|
|
102
|
+
```json
|
|
103
|
+
{ "mcpServers": { "prodex": { "command": "prodex", "args": ["mcp", "--cwd", "/absolute/path/to/your/repo"] } } }
|
|
318
104
|
```
|
|
319
105
|
|
|
320
|
-
|
|
106
|
+
The server exposes `pro_consult` (a visible-browser send, with the same model, effort, project and tool choices as the CLI), `pro_recover` (fetch an answer that finished after a timeout), the bridge ledger tools (`bridge_create_task`, `bridge_list_tasks`, `bridge_fetch_result`, receipts, sessions), bounded `repo_read_file` and `repo_search`, and a receipt-gated write path: `repo_write_file_dry_run` first, `repo_write_file_apply` only while git HEAD and the file's preimage hash still match, `repo_stage_reviewed_paths` for applied receipts only. No shell tool, no ungated write. `prodex claude prompt` prints a paste-ready prompt that verifies the wiring. [docs/claude.md](docs/claude.md) covers Claude Desktop and Claude Code; [docs/clients.md](docs/clients.md) covers the others, including the per-call approval and `tool_timeout_sec` Codex needs.
|
|
321
107
|
|
|
322
|
-
|
|
108
|
+
An MCP server usually starts without `--cwd`, so a per-repo default can be missed. For defaults that apply from any directory, set `PRODEX_DEFAULT_PROJECT`, `PRODEX_DEFAULT_MODEL`, `PRODEX_DEFAULT_EFFORT` or `PRODEX_DEFAULT_PRO_MODE` in the agent's MCP `env` block; a per-repo config still wins field by field.
|
|
323
109
|
|
|
324
|
-
|
|
325
|
-
prodex pro browser ask --cwd /absolute/path/to/your/repo --target-url "https://chatgpt.com/c/..." --confirm-target --file README.md "Review this in this thread"
|
|
326
|
-
```
|
|
327
|
-
|
|
328
|
-
`prodex` does not silently switch Projects or threads. If the visible ChatGPT tab is not already on the confirmed URL, the send is refused.
|
|
329
|
-
If more than one ChatGPT tab or window is visible or visibility cannot be verified for extra ChatGPT tabs, an untargeted browser send is also refused; close the extra ChatGPT windows or use `--target-url ... --confirm-target`.
|
|
330
|
-
|
|
331
|
-
For optional ChatGPT Project -> local handoff, start the HTTP MCP bridge:
|
|
110
|
+
**ChatGPT Projects** can hand structured tasks back to your machine over a loopback-only HTTP MCP bridge. Token-bearing MCP URLs are secrets: the URL authorizes every enabled tool, so it is printed only on request and belongs only in your own trusted Project configuration.
|
|
332
111
|
|
|
333
|
-
```
|
|
112
|
+
```sh
|
|
334
113
|
prodex setup --token-ttl-hours 24
|
|
335
114
|
prodex start
|
|
115
|
+
prodex status --show-token --url-only # the paste-ready URL, token included
|
|
116
|
+
prodex project prompt # a paste-ready verification prompt for the Project
|
|
336
117
|
```
|
|
337
118
|
|
|
338
|
-
|
|
339
|
-
The HTTP MCP listener is loopback-only: `setup --host` accepts local loopback hosts such as `127.0.0.1` or `localhost`, not public interfaces like `0.0.0.0`.
|
|
340
|
-
`start` reads the saved setup profile when the server process starts. If you rerun `setup` to change the listener or rotate the token, restart `prodex start` so the running server uses the new profile. `status --show-token --url-only` prints the saved local MCP URL, while `tunnel url` formats your supplied public tunnel URL with the saved token; it does not create or inspect the tunnel.
|
|
341
|
-
|
|
342
|
-
Run these commands from the repo root, or add `--cwd /absolute/path/to/your/repo` to `setup`, `start`, `status`, `doctor`, `tunnel url`, and bridge inspection commands. For example:
|
|
343
|
-
|
|
344
|
-
```bash
|
|
345
|
-
prodex setup --cwd /absolute/path/to/your/repo --token-ttl-hours 24
|
|
346
|
-
prodex start --cwd /absolute/path/to/your/repo
|
|
347
|
-
```
|
|
119
|
+
The listener binds loopback only; put your own tunnel in front of it if ChatGPT cannot reach `127.0.0.1`, and only with a short-lived token (`prodex tunnel url --public-url https://... --show-token --url-only` formats the URL). [docs/http-mcp.md](docs/http-mcp.md) has the full flow and the safety notes.
|
|
348
120
|
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
```bash
|
|
352
|
-
node dist/cli.js start --cwd /absolute/path/to/your/repo --source-cli /absolute/path/to/prodex/dist/cli.js
|
|
353
|
-
node dist/cli.js status --cwd /absolute/path/to/your/repo --source-cli /absolute/path/to/prodex/dist/cli.js --show-token --url-only
|
|
354
|
-
```
|
|
355
|
-
|
|
356
|
-
Token-bearing MCP URLs are secrets. They authorize all enabled bridge tools, including repo read, search, write dry-run/apply, and stage-reviewed-paths tools. Use the next command only when you are ready to paste the URL into your own trusted private ChatGPT Project/App configuration:
|
|
357
|
-
|
|
358
|
-
```bash
|
|
359
|
-
prodex status --show-token --url-only
|
|
360
|
-
```
|
|
121
|
+
## Model, effort and project
|
|
361
122
|
|
|
362
|
-
|
|
123
|
+
ChatGPT's composer picker is one slider that walks model and effort together. prodex drives that slider, and reads it back before every send:
|
|
363
124
|
|
|
364
|
-
|
|
125
|
+
```console
|
|
126
|
+
$ prodex pro browser models
|
|
127
|
+
Model menu options in the visible ChatGPT tab (read-only; nothing was selected):
|
|
128
|
+
* Latest
|
|
129
|
+
GPT-5.6 Sol
|
|
130
|
+
GPT-5.5
|
|
365
131
|
|
|
366
|
-
|
|
367
|
-
|
|
132
|
+
Power slider on this account (the slider was walked and put back):
|
|
133
|
+
1/5 Latest - Instant
|
|
134
|
+
2/5 Latest - Medium
|
|
135
|
+
3/5 Latest - High
|
|
136
|
+
4/5 Latest - Extra High
|
|
137
|
+
* 5/5 6 - Pro
|
|
368
138
|
```
|
|
369
139
|
|
|
370
|
-
|
|
140
|
+
- `--effort 즉시|중간|높음|"매우 높음"|Pro` picks a rung; English aliases `instant`, `medium`, `high`, `extrahigh` and `max` are accepted, and `--model Pro` reaches the same top rung. Korean and English (US) ChatGPT labels are both matched; on another display language, pass the exact label `models` shows.
|
|
141
|
+
- ChatGPT now has two surfaces, Chat and Work, with different pickers; Work's ladder ends in Max and Ultra and offers no Pro. prodex puts the browser back on Chat before a send (and says so on the receipt), so a drifted browser cannot quietly send on the wrong picker. `Max` and `Ultra` are accepted for a browser already on Work.
|
|
142
|
+
- The model rows themselves (Latest, GPT-5.6 Sol, GPT-5.5) cannot be clicked by automation in the current picker; the slider is the lever, and prodex says so rather than pretending a row was chosen.
|
|
143
|
+
- Selection is guarded: a control that is covered or off screen is not clicked, a menu that stays open after a pick counts as a failed pick, and any failure backs out with Escape and reports a blocker instead of sending with the wrong model. What was applied is recorded on the receipt (`metadata.selection`, project name redacted).
|
|
371
144
|
|
|
372
|
-
|
|
373
|
-
node dist/cli.js project prompt --cwd /absolute/path/to/your/repo --source-cli /absolute/path/to/prodex/dist/cli.js
|
|
374
|
-
```
|
|
375
|
-
|
|
376
|
-
Paste that prompt into the ChatGPT Project. It asks ChatGPT to call `bridge_create_task`, `bridge_list_tasks`, and `bridge_get_task`, then wait while you complete the verification task locally:
|
|
145
|
+
Pin defaults once per repo so routine asks need no flags; a per-ask flag always wins:
|
|
377
146
|
|
|
378
|
-
```
|
|
379
|
-
prodex
|
|
380
|
-
prodex
|
|
381
|
-
prodex
|
|
147
|
+
```sh
|
|
148
|
+
prodex setup --effort Pro --project "your-project"
|
|
149
|
+
prodex setup --clear-project
|
|
150
|
+
prodex setup --interactive # a short wizard instead of flags
|
|
151
|
+
prodex status # shows the saved defaults
|
|
382
152
|
```
|
|
383
153
|
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
The generated prompt also includes local `status --cwd ...` and `doctor --cwd ...` troubleshooting commands in case the Project cannot see or call the MCP tools. Source-checkout prompts keep `--source-cli` on those troubleshooting commands too.
|
|
387
|
-
|
|
388
|
-
If ChatGPT cannot reach `127.0.0.1` from its app runtime, keep `prodex start` local and put your own tunnel in front of it only after creating a short-lived token. `prodex` does not create the tunnel for you, but it can format the public MCP URL safely.
|
|
389
|
-
|
|
390
|
-
Public tunnel MCP URLs are also secrets. They authorize all enabled bridge tools, including repo read, search, write dry-run/apply, and stage-reviewed-paths tools. Use the next command only when you are ready to paste the public URL into your own trusted private MCP client configuration:
|
|
154
|
+
## Running without a window
|
|
391
155
|
|
|
392
|
-
```
|
|
393
|
-
prodex
|
|
156
|
+
```sh
|
|
157
|
+
prodex pro browser login # once, headed: sign in
|
|
158
|
+
prodex pro browser login --virtual-display # from then on: no window anywhere
|
|
394
159
|
```
|
|
395
160
|
|
|
396
|
-
|
|
161
|
+
`--virtual-display` (or `PRODEX_VIRTUAL_DISPLAY=1`, which the MCP server and its auto-recovery honour too) starts an X virtual framebuffer and runs the dedicated Chrome on it. It is a real headed browser, so Cloudflare treats it as one: measured end to end, the signed-in profile loaded chatgpt.com with no challenge and a Pro send returned normally, with nothing on the desktop. Linux and WSL; needs `xvfb` and `xauth`, and the display is protected by a per-display xauth cookie rather than opened to every process.
|
|
397
162
|
|
|
398
|
-
|
|
163
|
+
`--minimized` keeps a window but minimizes it. Under WSLg a minimized Chrome still reports itself visible and consults keep working; a normal Linux desktop marks it hidden, and prodex refuses to send into a tab it cannot read, restores the window, and tells you.
|
|
399
164
|
|
|
400
|
-
|
|
401
|
-
- `repo_write_file_apply` applies that receipt only when the current git HEAD and file preimage hash still match.
|
|
402
|
-
- `repo_stage_reviewed_paths` stages only files whose applied write receipts still match the current git HEAD and file content.
|
|
403
|
-
- Sensitive local paths are rejected by both the read and write tools: `.bridge`, `.git`, `.env*`, `node_modules`, `dist`, and a set of common in-repo credential/key files (for example `.npmrc`, `.netrc`, `id_rsa`/`id_ed25519`, `*.pem`, `*.key`, `*.p12`/`*.pfx`/`*.jks`, `*.tfstate`, `credentials.*`, `service-account.*`, and the `.ssh`/`.aws`/`.gnupg` directories). This blocklist is defense in depth, not an exhaustive secret scanner — traversal and symlink escapes are separately blocked, but keep genuine secrets out of the repo and treat a token-bearing MCP URL as authorizing everything the tools can reach.
|
|
404
|
-
- No shell execution or direct ungated staging tool is exposed.
|
|
165
|
+
`--headless` exists and is not usable against ChatGPT today: measured on a signed-in profile, headless Chrome stays on Cloudflare's interstitial past sixty seconds. Only the window is optional; the login is not.
|
|
405
166
|
|
|
406
|
-
|
|
167
|
+
A browser that stops answering its control port mid-send is ended and started fresh before the send, and the receipt says so (`PRODEX_NO_AUTO_CLEAR=1` turns that off). A browser that is merely slow is left alone.
|
|
407
168
|
|
|
408
|
-
|
|
409
|
-
cd /absolute/path/to/your/repo
|
|
410
|
-
prodex doctor
|
|
411
|
-
prodex tasks create --cwd /absolute/path/to/your/repo --title "Review plan" --prompt "Review this architecture"
|
|
412
|
-
prodex tasks list --cwd /absolute/path/to/your/repo
|
|
413
|
-
prodex tasks show latest --cwd /absolute/path/to/your/repo
|
|
414
|
-
prodex tasks block <task-id> --cwd /absolute/path/to/your/repo --summary "Blocked reason" --code manual_blocker --next-step "What to do next" --retryable
|
|
415
|
-
prodex pro ask --dry-run --cwd /absolute/path/to/your/repo --file README.md "Review the project positioning"
|
|
416
|
-
prodex sessions list
|
|
417
|
-
```
|
|
418
|
-
|
|
419
|
-
`doctor` stays local: it does not open ChatGPT or a browser. It creates isolated temp workspaces for the write/apply/stage smoke and HTTP MCP smoke, then confirms the expected bridge/repo tools are visible and that task create/list/get/claim/complete/block/fetch/list-results works over the MCP protocol.
|
|
169
|
+
## Receipts
|
|
420
170
|
|
|
421
|
-
|
|
171
|
+
Everything a consult touches is written under `.bridge/` in the repo it ran from:
|
|
422
172
|
|
|
423
|
-
```
|
|
424
|
-
|
|
173
|
+
```text
|
|
174
|
+
.bridge/
|
|
175
|
+
tasks/ what was asked, by whom, with which files and tools
|
|
176
|
+
results/ the answer's summary and the artifacts it produced
|
|
177
|
+
sessions/ preview, running, done or blocked, per consult
|
|
178
|
+
receipts/ HMAC-signed records of every action, keyed by .bridge/receipt-key.local
|
|
179
|
+
artifacts/ pro-consults/ answers, results/ handoff artifacts, repo-writes/ staged text
|
|
180
|
+
diagnostics/ screenshots and page-shape snapshots from failed sends, when enabled
|
|
425
181
|
```
|
|
426
182
|
|
|
427
|
-
|
|
183
|
+
`prodex init` creates the ledger (a browser send creates it on first use too). `prodex pro latest`, `pro show`, `results show`, `results artifact`, `receipts show` and `sessions show` read them; `--json` on the list commands gives structured output. Result artifacts are checked against the sha256 recorded when they were finalized. A blocked consult is completed as blocked with its code and next step, so `pro latest` shows what happened even when nothing was sent. `prodex receipts rotate-key` signs new receipts with a fresh key while older ones stay verifiable; `prodex results reseal <task-id> --confirm-current-result` re-signs a legacy result you have reviewed.
|
|
428
184
|
|
|
429
|
-
prodex
|
|
185
|
+
Two sibling tools read the same ledger, found through the bridge registry prodex keeps in `~/.local/share/prodex/bridges.json`: [sessionwiki](https://github.com/youdie006/sessionwiki) indexes every consult as a searchable session, and [swapdex](https://github.com/youdie006/swapdex) lists recent consults after an account switch. Neither is required.
|
|
430
186
|
|
|
431
|
-
|
|
187
|
+
## How it works
|
|
432
188
|
|
|
433
|
-
```
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
```bash
|
|
443
|
-
PRODEX_BROWSER_DIAGNOSTICS=1 prodex ask "..."
|
|
444
|
-
# .bridge/diagnostics/<when>/{screen.png,page-shape.json}
|
|
189
|
+
```text
|
|
190
|
+
you / prodex ask ---------+
|
|
191
|
+
| Chrome DevTools Protocol (loopback)
|
|
192
|
+
Claude, Codex, Cursor ----+--> prodex ------------------------------------> dedicated Chrome, your login
|
|
193
|
+
stdio MCP: pro_consult | | |
|
|
194
|
+
| | tasks, results, sessions, receipts | chatgpt.com, the same
|
|
195
|
+
ChatGPT Projects ---------+ v | composer you would use
|
|
196
|
+
loopback HTTP MCP .bridge/ (in your repo, HMAC-signed) v
|
|
197
|
+
ChatGPT Pro
|
|
445
198
|
```
|
|
446
199
|
|
|
447
|
-
The
|
|
200
|
+
The browser is a real Chrome launched with `--remote-debugging-port` on `127.0.0.1`, live only while that window is open. prodex checks the page state, confirms the tab is on a ChatGPT conversation it can read, applies the picker selection, types the prompt, waits for the answer to finish, and reads it from the transcript. Sends are paced to human speed (one every ten seconds by default, `PRODEX_MIN_SEND_INTERVAL_MS` tunes it) and take a cross-process lock, so two agents on one machine queue rather than fight over the composer.
|
|
448
201
|
|
|
449
|
-
|
|
202
|
+
### What it will not do
|
|
450
203
|
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
204
|
+
- No hidden ChatGPT endpoints, no cookie, token, localStorage or sessionStorage extraction. It never reads a credential; the browser holds your login.
|
|
205
|
+
- No captcha solving, Cloudflare bypass, proxies or stealth. Login, captcha, verification, usage and model limits stop the send with a named blocker.
|
|
206
|
+
- No batch prompting or recurring loops. It is built for the occasional consult a person would make, and the pacing enforces that.
|
|
207
|
+
- No shell tool and no ungated write over MCP. Reads and searches are bounded to the repo and refuse `.bridge`, `.git`, `.env*`, `node_modules`, `dist` and common credential files.
|
|
208
|
+
- Nothing leaves your machine except what you type into ChatGPT. Bridge endpoints bind loopback; exposing them is your call and your tunnel.
|
|
455
209
|
|
|
456
|
-
|
|
210
|
+
Automating a paid ChatGPT account is your responsibility under OpenAI's terms; prodex keeps it visible and slow so that it looks like what it is.
|
|
457
211
|
|
|
458
|
-
##
|
|
212
|
+
## When a send breaks
|
|
459
213
|
|
|
460
|
-
|
|
214
|
+
prodex drives a web UI that changes underneath it, so the tooling assumes it will.
|
|
461
215
|
|
|
462
|
-
```
|
|
463
|
-
prodex
|
|
216
|
+
```sh
|
|
217
|
+
prodex pro report-issue # a GitHub issue drafted from the blocked consult's receipt
|
|
218
|
+
prodex pro report-issue --confirm # files it through gh; the prompt and the answer never travel
|
|
219
|
+
PRODEX_BROWSER_DIAGNOSTICS=1 prodex ask "..." # leaves a screenshot and a page-shape snapshot in .bridge/diagnostics/
|
|
220
|
+
node scripts/ui-watchdog.mjs # a real round trip that says ok or broken; --file-issue reports it
|
|
464
221
|
```
|
|
465
222
|
|
|
466
|
-
|
|
223
|
+
Reports are deduplicated by blocker code, so something that stays broken adds to one issue. Captures stay on your machine.
|
|
467
224
|
|
|
468
225
|
## FAQ
|
|
469
226
|
|
|
470
|
-
**A send failed with `send_ui_changed
|
|
471
|
-
|
|
472
|
-
**A send stopped or "won't send" — why?** A tab counts as watchable only while its window is non-minimized and it is the active tab in that window. If you minimized the dedicated Chrome or switched it to another tab, the send stops with a `tab_not_visible` blocker rather than sending where you cannot watch. Leaving that window non-minimized behind your other apps is fine — it still sends in the background. By design `prodex` does not steal focus; if you'd rather it pull the tab to the front on a stopped send, set `PRODEX_ACTIVATE_TAB=1` (off by default so background loops aren't interrupted). Other stops (login, captcha, Cloudflare, rate/usage limit) are reported with a blocker code and next step, and recorded so `prodex pro latest` shows what happened.
|
|
473
|
-
|
|
474
|
-
**I run consults in the background while working elsewhere — will the window keep popping up?** No. By default `prodex` never brings the window forward. Dedicate a Chrome window to the ChatGPT tab, leave it non-minimized behind your editor, and sends run silently. (On macOS a fully occluded window can report itself hidden even when not minimized; if that bites you, keep a sliver visible or accept the occasional blocker.)
|
|
475
|
-
|
|
476
|
-
**Why did it pause before sending?** Visible-browser sends are throttled to human pace (default one every 10 seconds) so an agent loop can't hammer ChatGPT at machine speed. You'll see a `send_pacing: waiting Ns` note on stderr. Tune it with `PRODEX_MIN_SEND_INTERVAL_MS` (milliseconds; `0` disables). Pacing is tracked per repo via `.bridge/last-browser-send`.
|
|
477
|
-
|
|
478
|
-
**The browser was closed — do I have to run `login` again?** Not in a terminal: an interactive `ask` notices `browser_unreachable`, relaunches the dedicated browser, waits for your saved session to report READY, and retries the send once. Scripts opt in with `--auto-login`; `--no-auto-login` disables it. Only a missing browser triggers this — login/captcha/limit blockers still stop and report.
|
|
479
|
-
|
|
480
|
-
**The answer timed out.** Pro reasoning can take many minutes. A Pro selection already raises the default budget to 900s; the `send_timeout` blocker suggests a paste-ready rerun command with a doubled `--timeout-ms`. If the answer was mid-stream when time ran out, prodex salvages the partial text and records an `answer_incomplete` warning instead of discarding it.
|
|
227
|
+
**A send failed with `send_ui_changed`.** ChatGPT redesigned the composer or send control. Update (`npm i -g @youdie006/prodex@latest`); if it persists, `prodex pro report-issue`, and paste the prompt by hand meanwhile.
|
|
481
228
|
|
|
482
|
-
**
|
|
229
|
+
**It stopped with `tab_not_visible`.** A tab counts as watchable only while its window is not minimized and it is the active tab. Leave the dedicated window behind your editor and it sends in the background; prodex never steals focus (`PRODEX_ACTIVATE_TAB=1` if you want the tab pulled forward on a stopped send).
|
|
483
230
|
|
|
484
|
-
**
|
|
231
|
+
**Why the pause before sending?** Pacing: `send_pacing: waiting Ns` on stderr. `PRODEX_MIN_SEND_INTERVAL_MS=0` disables it.
|
|
485
232
|
|
|
486
|
-
**
|
|
233
|
+
**The answer timed out.** Pro can take many minutes; the `send_timeout` blocker prints a rerun command with a doubled budget, and a partial answer is kept with an `answer_incomplete` warning. If the thread finished after the timeout, `prodex pro browser recover --target-url <thread>` fetches it, deep research reports included.
|
|
487
234
|
|
|
488
|
-
**
|
|
235
|
+
**Sends started failing after many consults in one chat.** Long threads confuse prompt-acceptance detection. Use `--new-chat` (`new_chat: true` on the MCP tool).
|
|
489
236
|
|
|
490
|
-
**
|
|
237
|
+
**Every send says "still generating" and nothing is being written.** ChatGPT parked the thread on "which response do you prefer?". prodex reports `response_choice_pending` and names the buttons; pick one, or send with `--new-chat`.
|
|
491
238
|
|
|
492
|
-
**
|
|
239
|
+
**Does it read my cookies or tokens?** No. It talks to the browser only over the loopback DevTools port, and only while that browser is open.
|
|
493
240
|
|
|
494
|
-
|
|
241
|
+
**Windows and macOS?** All three platforms are targeted; the visible-browser adapter is exercised most on Linux and WSL. Open an issue with details if a browser step misbehaves elsewhere.
|
|
495
242
|
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
Release flow:
|
|
499
|
-
|
|
500
|
-
```bash
|
|
501
|
-
# 1. bump version + update CHANGELOG on main, commit, push main
|
|
502
|
-
# 2. tag the release and push the tag — CI publishes it
|
|
503
|
-
git tag v0.8.2
|
|
504
|
-
git push origin v0.8.2
|
|
505
|
-
```
|
|
506
|
-
|
|
507
|
-
`.github/workflows/publish.yml` fires on a `v*.*.*` tag: it checks out, installs, verifies the tag equals `package.json`'s version, runs `release:verify`, and publishes with `npm publish --provenance --access public`. The tag/version guard prevents publishing a mismatched version.
|
|
508
|
-
|
|
509
|
-
One-time setup (owner, on npmjs.com): open the package → Settings → Trusted Publishing → add a GitHub Actions publisher for repo `youdie006/prodex` and workflow `publish.yml`. After that, no npm tokens are needed anywhere; revoke any previously issued automation tokens.
|
|
510
|
-
|
|
511
|
-
## Release Checks
|
|
512
|
-
|
|
513
|
-
GitHub Actions runs `npm ci`, `npm run build`, `npm run release:check`, and `npm run release:verify` on pushes to `main` and pull requests. The workflow installs `ripgrep` because the repo-search smoke checks require `rg`. It verifies release readiness only; it does not publish anything.
|
|
514
|
-
|
|
515
|
-
Before sharing a package tarball, run:
|
|
516
|
-
|
|
517
|
-
```bash
|
|
518
|
-
npm run smoke:package
|
|
519
|
-
```
|
|
243
|
+
## Development
|
|
520
244
|
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
npm run release:verify
|
|
527
|
-
```
|
|
528
|
-
|
|
529
|
-
This runs tests, typecheck, build, package smoke, and `doctor` without weakening the publish guard.
|
|
530
|
-
|
|
531
|
-
If direct `npm pack` is blocked because a WSL/Windows mount reports normal source files as executable, build the publish tarball from a temporary Linux staging directory:
|
|
532
|
-
|
|
533
|
-
```bash
|
|
534
|
-
prodex release pack --pack-destination /tmp/prodex-release
|
|
535
|
-
```
|
|
536
|
-
|
|
537
|
-
For a source checkout, use the built CLI with `--source-cli` so follow-up commands stay in source-checkout form:
|
|
538
|
-
|
|
539
|
-
```bash
|
|
540
|
-
cd /absolute/path/to/prodex
|
|
541
|
-
SOURCE_CLI="/absolute/path/to/prodex/dist/cli.js"
|
|
542
|
-
node "$SOURCE_CLI" release pack --source-cli "$SOURCE_CLI" --pack-destination /tmp/prodex-release
|
|
543
|
-
node "$SOURCE_CLI" release status --source-cli "$SOURCE_CLI"
|
|
544
|
-
```
|
|
545
|
-
|
|
546
|
-
The npm script is equivalent when you only need the tarball:
|
|
547
|
-
|
|
548
|
-
```bash
|
|
549
|
-
npm run release:pack -- --pack-destination /tmp/prodex-release
|
|
550
|
-
```
|
|
551
|
-
|
|
552
|
-
For source-checkout release commands, prefer the CLI wrapper when you want follow-up guidance to stay in `node dist/cli.js ... --source-cli` form. The npm script creates the same normalized tarball, but it cannot know which source CLI path should appear in later recovery commands.
|
|
553
|
-
|
|
554
|
-
`release pack` does not publish anything. It still refuses missing publish metadata, non-regular or hard-linked packed files, and missing package release checks; it only normalizes packed file modes in the staging copy so package `bin` entries remain executable and other packed files become regular `0644` files. Run `npm run release:verify` and the matching status command before publishing the tarball it creates: `prodex release status` for installed-package use, or `node /absolute/path/to/prodex/dist/cli.js release status --source-cli /absolute/path/to/prodex/dist/cli.js` from a source checkout. When the tarball is ready, `release pack` prints `release_pack_git` and `release_pack_git_next` lines before publish guidance so git remote/upstream blockers stay visible. It always prints `npm publish --dry-run <tarball>` for inspecting the exact tarball. Tarball publish commands bypass npm `prepublishOnly`, so `release pack` prints `release_pack_publish_guard` before `npm publish <tarball>`; run the dry-run command first, then publish only that verified tarball if it succeeds. If git readiness is blocked, it prints `release_pack_publish_blocked` instead.
|
|
555
|
-
|
|
556
|
-
Add `--keep-workdir` to `prodex release pack`, `node /absolute/path/to/prodex/dist/cli.js release pack --source-cli /absolute/path/to/prodex/dist/cli.js --pack-destination <dir>`, or `npm run release:pack -- ...` when you need to inspect the temporary normalized staging directory.
|
|
557
|
-
|
|
558
|
-
To see the current publish blocker and next step from the CLI:
|
|
559
|
-
|
|
560
|
-
```bash
|
|
561
|
-
prodex release status
|
|
562
|
-
```
|
|
563
|
-
|
|
564
|
-
It reports package metadata blockers, pack file-mode, non-regular file, or hard-link blockers when package identity is readable, and local git readiness, including a dirty worktree, detached HEAD, missing git remote, branch without upstream tracking, upstream is gone, branch divergence, unpushed local commits, or a branch behind upstream. For a new public repo, create the remote yourself, then run `git remote add origin <git-url>` and `git push -u origin <branch>`; `release status` prints those handoff commands when the local git state is missing a remote or upstream.
|
|
565
|
-
|
|
566
|
-
Before publishing to npm, make sure `package.json` has an npm-publishable `name` and valid semver `version`, keep the explicit MIT `license` metadata and matching `LICENSE` regular file, and make sure `package.json` does not have `private: true`. `release:check` treats missing or malformed package identity and `private: true` as publish blockers because npm will refuse to publish those packages. It also rejects a `LICENSE` path that is a directory, symlink, or hard link, rejects non-regular or symlinked packed files, blocks packed files with unexpected executable modes outside package `bin` entries, and rejects hard-linked packed files. If you are on a WSL/Windows mount that reports every file as executable, publish from a Linux filesystem, fix mount metadata/chmod first, or use `prodex release pack --pack-destination <dir>` after release verification to create the tarball from normalized staging files. From a source checkout, use `node /absolute/path/to/prodex/dist/cli.js release pack --source-cli /absolute/path/to/prodex/dist/cli.js --pack-destination <dir>` for the same normalized tarball plus source-aware follow-up guidance. Source-tree `npm publish` is intentionally guarded by `prepublishOnly`; it runs:
|
|
567
|
-
|
|
568
|
-
```bash
|
|
569
|
-
npm run release:check
|
|
570
|
-
```
|
|
571
|
-
|
|
572
|
-
If package metadata stops being publishable, `release:check` fails with a metadata error instead of letting an accidental public publish proceed. Use `npm run release:verify` when you only want local verification without claiming publish readiness.
|
|
573
|
-
|
|
574
|
-
## Claude MCP
|
|
575
|
-
|
|
576
|
-
If `prodex` is installed and on your PATH, generate the Claude MCP config JSON:
|
|
577
|
-
|
|
578
|
-
```bash
|
|
579
|
-
prodex claude config --cwd /absolute/path/to/your/repo
|
|
580
|
-
```
|
|
581
|
-
|
|
582
|
-
It prints this token-free config:
|
|
583
|
-
|
|
584
|
-
```json
|
|
585
|
-
{
|
|
586
|
-
"mcpServers": {
|
|
587
|
-
"prodex": {
|
|
588
|
-
"command": "prodex",
|
|
589
|
-
"args": ["mcp", "--cwd", "/absolute/path/to/your/repo"]
|
|
590
|
-
}
|
|
591
|
-
}
|
|
592
|
-
}
|
|
593
|
-
```
|
|
594
|
-
|
|
595
|
-
For a source checkout, first run `npm install && npm run build`, then generate a `node dist/cli.js` config:
|
|
596
|
-
|
|
597
|
-
```bash
|
|
598
|
-
node dist/cli.js claude config --cwd /absolute/path/to/your/repo --source-cli /absolute/path/to/prodex/dist/cli.js
|
|
599
|
-
```
|
|
600
|
-
|
|
601
|
-
See [docs/claude.md](docs/claude.md) for Claude Desktop and Claude Code notes.
|
|
602
|
-
Both generated configs point Claude at the same `mcp --cwd /absolute/path/to/your/repo` server args.
|
|
603
|
-
|
|
604
|
-
After adding the MCP server in Claude, generate a paste-ready verification prompt:
|
|
605
|
-
|
|
606
|
-
```bash
|
|
607
|
-
prodex claude prompt --cwd /absolute/path/to/your/repo
|
|
245
|
+
```sh
|
|
246
|
+
npm install
|
|
247
|
+
npm run build
|
|
248
|
+
npm test # 1000+ tests; none of them touch a real browser
|
|
249
|
+
npm run release:verify # tests, typecheck, build, package smoke, doctor
|
|
608
250
|
```
|
|
609
251
|
|
|
610
|
-
|
|
252
|
+
The npm package is CLI-only: the `prodex` command, the stdio MCP server and the HTTP MCP server are the supported surfaces, and deep imports are blocked on purpose. [docs/cli-reference.md](docs/cli-reference.md) carries the full operational detail: every command in installed and source-checkout form, the first login step by step, the HTTP bridge setup, and the local smoke tests. [docs/releasing.md](docs/releasing.md) describes the tag-driven publish (npm trusted publishing, no long-lived token) and the release checks.
|
|
611
253
|
|
|
612
|
-
|
|
613
|
-
node dist/cli.js claude prompt --cwd /absolute/path/to/your/repo --source-cli /absolute/path/to/prodex/dist/cli.js
|
|
614
|
-
```
|
|
254
|
+
## License
|
|
615
255
|
|
|
616
|
-
|
|
256
|
+
MIT. See [LICENSE](LICENSE).
|