Skip to content

cli-reference.md

Latest commit

 

History

History
409 lines (286 loc) · 35.2 KB

cli-reference.md

File metadata and controls

409 lines (286 loc) · 35.2 KB
Raw

CLI reference

The operational detail behind the README: the agent bridge over MCP, the first login step by step, source-checkout forms of every command, the HTTP MCP bridge for ChatGPT Projects, the receipt commands, and the local smoke tests. Sections are grouped the way the README introduces them; commands are shown for an installed prodex and, where they differ, for a source checkout.

What is implemented

Implemented:

  • Versioned .bridge ledger schemas for tasks, results, sessions, and receipts.
  • CLI commands for task creation/listing/inspection/claiming/completion/blocking and result display.
  • pro ask and pro latest for Codex-first consult previews and review receipts.
  • sessions list and sessions show for inspecting dry-run, running, done, or blocked consult sessions.
  • receipts list and receipts show for inspecting the local action ledger without exposing legacy inline write payloads.
  • Ledger MCP tools for creating, claiming, completing, blocking, and inspecting task/result/session/receipt records from Claude or ChatGPT Projects.
  • Read-only result artifact fetch for Pro consult and generic MCP handoff artifacts explicitly listed on result records.
  • Explicit local reseal for legacy signed result receipts after reviewing the current result payload.
  • pro browser login/check/smoke/ask for the optional visible browser adapter.
  • Claude-compatible stdio MCP server through prodex mcp.
  • ChatGPT Developer Mode-style Streamable HTTP MCP server through prodex setup and prodex start.
  • Read-only repo tools for bounded file reads and ripgrep search.
  • 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.
  • doctor local health check for .bridge, redacted config loading, receipt-backed write/apply/stage, and the real HTTP MCP tool catalog.

Not implemented:

  • Hidden ChatGPT endpoints.
  • Cookie, token, localStorage, or sessionStorage extraction.
  • Direct ungated write tools.
  • Shell execution tools.
  • Automatic public tunnel setup.

Agent Bridge Quick Start

This section connects coding agents (Claude, Codex, ChatGPT Projects) to the bridge over MCP. It is not required for the standalone terminal flow above — if you only want Pro answers in your terminal, the Quickstart is complete on its own.

Requires Node.js 20 or newer, git, and ripgrep (rg) on PATH. The optional browser adapter probes PATH binaries (google-chrome, chromium, chromium-browser, microsoft-edge, brave-browser), native macOS app bundles, and native Windows Program Files/LOCALAPPDATA installs. Set PRODEX_CHROME for another executable. WSL uses Linux browser paths, not automatic Windows-host browser discovery. Do not share one profile between native Windows Chrome and Linux Chrome. See platform verification and local storage permissions.

Native Windows command examples use PowerShell quoting, including doubled apostrophes inside single-quoted arguments. Use PowerShell 7 for compound examples containing &&; these examples are not cmd.exe commands. Internal CLI/MCP child processes receive literal argument arrays without a shell.

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:

npm install -g @youdie006/prodex

The prodex command is then on your PATH:

prodex onboard
prodex init
prodex doctor
prodex pro ask --cwd /absolute/path/to/your/repo "Review the project positioning"

For a source checkout:

cd /absolute/path/to/prodex
npm install
npm run build
SOURCE_CLI="/absolute/path/to/prodex/dist/cli.js"
node "$SOURCE_CLI" onboard --source-cli "$SOURCE_CLI"
node "$SOURCE_CLI" init
node "$SOURCE_CLI" doctor --source-cli "$SOURCE_CLI"
node "$SOURCE_CLI" pro ask --cwd /absolute/path/to/your/repo "Review the project positioning"

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. onboard prints the Claude, ChatGPT Project, and optional ChatGPT Pro consult commands without changing local state.

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. Run init from the repo root, or use prodex init --cwd /absolute/path/to/your/repo from elsewhere.

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. 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. 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. 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". 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.

First Pro Login

Use this only when you explicitly want to use your logged-in ChatGPT Pro web session.

prodex pro browser login --dry-run
prodex pro browser login
prodex pro browser login --headed  # visible mode when no incompatible browser is running
prodex pro browser login --headed --recover-visible  # guarded recovery of a blocked headless browser
prodex pro browser help
prodex pro browser check
prodex pro browser smoke --cwd /absolute/path/to/your/repo

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.

For a source checkout, keep the follow-up commands in source-checkout form too:

cd /absolute/path/to/prodex
SOURCE_CLI="/absolute/path/to/prodex/dist/cli.js"
node "$SOURCE_CLI" pro browser login --dry-run --source-cli "$SOURCE_CLI"
node "$SOURCE_CLI" pro browser login --source-cli "$SOURCE_CLI"
node "$SOURCE_CLI" pro browser help --source-cli "$SOURCE_CLI"
node "$SOURCE_CLI" pro browser check --source-cli "$SOURCE_CLI"
node "$SOURCE_CLI" pro browser smoke --source-cli "$SOURCE_CLI" --cwd /absolute/path/to/your/repo

What happens:

  • login --dry-run prints the dedicated Chrome profile, debug URL, and next commands without opening a browser.
  • login opens that dedicated Chrome profile at ChatGPT. In an interactive terminal it then waits (default 5 minutes; --no-wait skips, --wait-timeout-ms tunes) and narrates which manual step is still missing until it reports READY; scripts and agents get the immediate return unless they pass --wait.
  • login reuses the last profile recorded for the resolved debug port when --profile-dir is omitted. It does not reuse a saved custom port implicitly: --port / PRODEX_CDP_PORT / the normal 9333 default still resolve the port exactly as before.
  • You log in manually only if the visible browser asks; an already signed-in profile is reused.
  • If ChatGPT asks for captcha, Cloudflare/human verification, permission, or account verification, handle it in that browser.
  • If ChatGPT shows a usage limit, message limit, model limit, or rate limit, wait for the reset or choose an available model in the browser.
  • Open a normal ChatGPT chat or the intended Project/thread so the prompt composer is visible.
  • Pick the Pro/Thinking model you want in the ChatGPT UI.
  • The login stays in the dedicated profile:
~/.local/share/prodex/chrome-chatgpt-pro

Closing that Chrome window does not switch to headless mode or prove that the saved login was erased. Keep it open for headed consults. Closing the terminal after READY is safe because Chrome is detached; closing the CLI or agent during a consult may interrupt answer collection.

For a one-time interactive login followed by a no-window handoff, run prodex pro browser login --background. It waits even without a terminal, verifies readiness, then under the shared send lock gracefully closes the idle dedicated browser and launches the same profile and conversation headless. Wait for background: READY. The resulting mode is recorded for future CLI/MCP relaunches. This option cannot be combined with other window modes or --no-wait; --dry-run previews without opening or closing anything. Other page targets (including Chrome account prompts), dialogs, drafts, attachments, active responses, and uncertain browser identity/shutdown stop the handoff. Headless authentication and protection checks are never bypassed.

To inspect an authentication/protection blocker in a running headless browser, explicitly use prodex pro browser login --headed --recover-visible. The command requires one verified dedicated headless browser and one ChatGPT page reporting login_required, cloudflare_check, captcha_required, or permission_required. It preserves the exact profile and page under the shared send lock, refuses unfinished inputs, active work, dialogs, attachments, extra tabs, and ambiguous identity, and waits for a verified shutdown before launching headed. It does not click, solve, or suppress a security check. Use --wait to wait for manual handling or --no-wait to return after launch; --dry-run performs no browser change. This is headless-only, not a generic reset or a virtual-display switch.

The visible recovery window does not change the headless relaunch preference. Once the dedicated browser fully exits, both a new login launch and an automatic browser restart use headless mode again. On macOS, closing its last window may leave the process running: automatic missing-tab recovery stops with browser_mode_transition_required instead of opening another visible window. Fully quit only the dedicated browser before retrying; the closed tab alone is not a reason to log in again. Reusing a still-open window with login --wait keeps the preference. An ordinary explicit window-mode option or environment override replaces it. There is no automatic headed fallback when the next headless launch encounters another challenge.

If only the ChatGPT tab was closed, MCP and auto-login-enabled CLI requests can reopen one tab in the existing browser before an unsent request. They verify the saved login before sending and never use this path to resend an accepted or uncertain request.

Before requesting --background, finish native browser and OS confirmations yourself. Page targets and rendered dialogs are checked, but Chrome does not expose every native prompt through CDP. Incognito/guest mode and an explicit --profile-directory are refused because their login identity cannot be safely handed off by this launcher.

Actual explicit visible-browser consult (prodex ask is the short form of prodex pro browser ask):

cd /absolute/path/to/your/repo
prodex ask --file README.md "Review the project positioning"
prodex pro latest
prodex results show latest
prodex results artifact latest
prodex sessions show latest

This uses the currently available ChatGPT web session and model selection. Each ordinary ask starts a fresh chat, including inside a configured project. Use --session-key <id> --continue for a follow-up scoped to one caller, or --continue-task <task_id> to deliberately name a consult across sessions. PRODEX_SESSION_KEY and then CODEX_THREAD_ID are the CLI fallbacks. It is not a hidden API client, and it does not read cookies, tokens, localStorage, or sessionStorage.

Current builds read rendered page content only. Project/conversation listings are limited to entries exposed by the UI. Automatic chat/project deletion and deep-research report retrieval are unsupported; those commands stop rather than call internal endpoints. Every send carries a visible request marker; success requires the returned assistant turn to follow that marker. Recover a timeout with --target-url <thread> --request-id <request_id> so recovery verifies the same turn. Omitting the request ID is legacy, unverified recovery. Formatting may differ from ChatGPT's rendered message.

Locks fail closed if a process is killed while reclaiming an abandoned lock. A leftover .reap claim then needs manual cleanup: first stop every prodex process using that resource and confirm no request/write/startup is active; only then remove the affected lock and its matching .reap file. Browser locks live beside the recorded send lock, repo-write locks under .bridge, and virtual-display allocation locks under ~/.local/share/prodex/xvfb. Do not remove a live request's lock to shorten a wait.

The automatic follow-up approval budget applies to MCP pro_consult, not these user-directed CLI commands. MCP callers should reuse returned continuation arguments and stop on awaiting_user until the user approves. See same-task dialogue for configuration and stop rules.

Choosing the model, reasoning effort, and project

The visible-browser send drives the same composer picker you use by hand. Since ChatGPT replaced the model menu with one power slider that walks model and effort together, that slider is the lever:

# The top rung: GPT-6 Pro
prodex pro browser ask --effort Pro "Review the migration plan"

# A lower rung, inside an existing sidebar project
prodex pro browser ask --effort "매우 높음" --project "my-project" "Draft the release notes"

To see the ladder your account currently shows, list it read-only (opens the menu, walks the slider and puts it back, presses Escape; nothing is selected):

prodex pro browser models
  • --effort 즉시|중간|높음|"매우 높음"|Max|Ultra|Pro sets the rung. English aliases instant/light, medium, high, extrahigh/max, ultra are accepted, and both the Korean and the English (US) ChatGPT labels are matched. Max and Ultra belong to the Work surface's ladder and apply only when the browser is already on Work; every other value is sent on Chat, whose top step is Pro.
  • --model Pro reaches the same top rung. The model rows in the picker (Latest, GPT-5.6 Sol, GPT-5.5) refuse automation clicks in the current UI - they carry pointer-events: none - so --model with any other label reports model_not_applied rather than pretending. On a display language other than Korean or English, pass the exact label models prints.
  • --pro-mode 기본|확장 selects a Pro sub-mode where the picker still exposes one (the GPT-5.5 generation); with a single Pro rung it fails with guidance. --pro-mode and --effort are different axes of the same control and cannot be combined. Any Pro selection raises the default --timeout-ms to 1200000, because Pro reasoning routinely runs for many minutes; an explicit --timeout-ms always wins.
  • ChatGPT keeps two surfaces, Chat and Work, with different pickers; Work's ladder has no Pro. A send puts the browser back on Chat first and notes it on the receipt, so a browser that drifted onto Work does not quietly send on the wrong picker.
  • --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.

Selection is 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. An applied selection stays active in your ChatGPT session after the send.

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:

prodex setup --model Pro --project "my-project"
prodex setup --clear-project
prodex setup --interactive   # asks model / Pro sub-mode or effort / project

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.

No window at all: virtual display (recommended)

Log in once, then never see the browser again:

prodex pro browser login                    # once, headed - sign in
prodex pro browser login --virtual-display  # from now on: no window anywhere
prodex pro browser login --headed            # force a visible window for login/captcha

Window mode is one mutually exclusive choice: --headed, --headless, --minimized, or --virtual-display. Supplying a CLI mode flag selects the whole mode and overrides environment and saved state. With no mode flag, any non-empty PRODEX_HEADLESS, PRODEX_MINIMIZE_WINDOW, or PRODEX_VIRTUAL_DISPLAY value selects the whole environment mode; 0, false, and no are meaningful false values, so PRODEX_HEADLESS=0 explicitly selects ordinary headed mode instead of falling back to a saved headless launch. With neither flags nor mode environment settings, login and CLI/MCP auto-recovery reuse the last recorded mode. With no saved record, the normal default is headed.

--virtual-display (or PRODEX_VIRTUAL_DISPLAY=1, which also covers the MCP server and its auto-recovery) starts an X virtual framebuffer and runs the dedicated Chrome on it. It is a real headed browser without a desktop window, not Chrome's headless mode. Login, captcha, rate limits, and permission checks still apply; this mode does not bypass them.

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. New displays use Linux abstract Unix sockets, which also work when WSLg mounts /tmp/.X11-unix read-only. TCP and filesystem Unix listeners are disabled. A per-display xauth cookie under ~/.local/share/prodex/xvfb/ restricts access to clients holding that credential; -ac is never used. The X server outlives the CLI on purpose (the browser runs on it) and is reused by later commands; PRODEX_VIRTUAL_DISPLAY_NUM selects the first number to try if :99 is taken. A setup failure stops the launch or recovery, without falling back to a desktop window.

Existing browsers and legacy TCP X servers are not stopped or migrated automatically. Finish pending consults, stop the dedicated browser and its old X server, then run the updated prodex pro browser login --virtual-display to migrate. New launches skip display numbers with an existing TCP listener and record the display number actually used.

A browser already running on your desktop cannot be moved onto a virtual display by reusing it. prodex refuses the switch without ending the browser; close it yourself, then rerun with the intended mode. Reinvoking login for an already-running virtual browser reuses its saved display identity and does not allocate another display.

Keeping the window, just out of the way

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 worked in the previous test where headless Chrome encountered a challenge. This is not a guarantee that future verification checks will pass.

The catch is what "minimized" means to your desktop. Under WSLg a minimized Chrome still reports visibilityState: "visible", so consults keep working (measured: a real Pro send completed in 26s with the window minimized). A normal Linux desktop instead marks minimized windows hidden, and prodex refuses to send into a tab it cannot read — so it restores the window and tells you, rather than leaving you a browser it cannot use. Try it; the login says which case you are in.

Headless mode (requires live readiness verification)

prodex pro browser login --headless (or PRODEX_HEADLESS=1, which also covers the MCP server and its auto-recovery) runs the dedicated browser with no visible window. Two constraints are real, not cosmetic:

  • Sign in headed first. Nobody can log in to a window that does not exist, so headless reuses a profile you already signed into. If the running headless browser reports login, captcha, Cloudflare, permission, or account verification, use prodex pro browser login --headed --recover-visible for a guarded switch to a visible interactive window. Do not merely omit --headless: saved modes persist.
  • One mode at a time. A single Chrome profile cannot serve a headed and a headless instance simultaneously. Use the guarded --background handoff for headed-to-headless operation or the explicit --headed --recover-visible recovery for a blocked headless browser. Other mode changes require closing the browser yourself.

A saved login does not guarantee headless readiness. A previous test on a signed-in profile remained on the "Just a moment..." interstitial past 60 seconds. That observation does not establish why the challenge appeared or prove that the saved login was lost. Require an actual READY result; if a protection check blocks the browser, stop and inspect it visibly. prodex does not invoke a hidden API or bypass login/protection. Only the window is optional; the login is not.

If a consult finds the browser closed, prodex now relaunches it in the same mode you last used and retries once — including from the MCP server, which has no terminal to prompt in. PRODEX_NO_AUTO_LOGIN=1 turns that off.

Whatever selection is applied is recorded on the consult receipt (metadata.selection); receipt display output redacts the project name, keeping only the model axes visible. prodex only clicks the picker you can see; it never selects a model, effort, or project silently outside the visible browser.

For a source checkout, keep the explicit send and inspection commands source-aware too:

cd /absolute/path/to/prodex
SOURCE_CLI="/absolute/path/to/prodex/dist/cli.js"
node "$SOURCE_CLI" pro browser ask --source-cli "$SOURCE_CLI" --cwd /absolute/path/to/your/repo --file README.md "Review the project positioning"
node "$SOURCE_CLI" pro latest --source-cli "$SOURCE_CLI"

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.

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.

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:

prodex results reseal <task-id> --confirm-current-result

This writes a new local task_completed receipt for the current result payload. Prefer the explicit task id you just reviewed; latest is accepted for convenience but resolves from the current raw result list at execution time. It does not reseal unsigned receipts, forged receipts, or receipts that already point at a different result digest.

Receipts are HMAC-signed with a local key in .bridge/receipt-key.local. If you suspect the key was exposed, rotate it:

prodex receipts rotate-key

New receipts are signed with the fresh key; previous keys stay in the file (verification only) so receipts signed before the rotation remain trusted.

To send into a specific visible Project or thread, open that ChatGPT URL in the dedicated browser first, confirm it is the right destination, then pass the same URL:

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"

prodex does not silently switch Projects or threads. If the visible ChatGPT tab is not already on the confirmed URL, the send is refused. 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.

For optional ChatGPT Project -> local handoff, start the HTTP MCP bridge:

prodex setup --token-ttl-hours 24
prodex start

setup writes .bridge/config.local.json and ensures .bridge/.gitignore covers local task/result/session/receipt/artifact/config files. setup, start, and status redact the URL token by default. 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. 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.

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:

prodex setup --cwd /absolute/path/to/your/repo --token-ttl-hours 24
prodex start --cwd /absolute/path/to/your/repo

For a source checkout, keep the source CLI path on runtime/status commands too so recovery hints stay copyable:

node dist/cli.js start --cwd /absolute/path/to/your/repo --source-cli /absolute/path/to/prodex/dist/cli.js
node dist/cli.js status --cwd /absolute/path/to/your/repo --source-cli /absolute/path/to/prodex/dist/cli.js --show-token --url-only

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:

prodex status --show-token --url-only

status --show-token requires a token with an expiry, so run setup --token-ttl-hours <hours> before asking for a paste-ready URL. The URL token is stored only in .bridge/config.local.json, which is ignored by git. Rotate it with setup --token-ttl-hours <hours>, then restart prodex start and update client URLs. Plain setup preserves the saved token and expiry, and unspecified listener settings are preserved. If you intentionally created a non-expiring token for local-only debugging, status --show-token refuses to reveal it unless you also pass --unsafe-show-non-expiring-token. doctor and pro browser check also print config_warning when the saved token is non-expiring.

After adding the MCP URL to ChatGPT, generate a paste-ready verification prompt:

prodex project prompt

For a source checkout, pass the same built CLI path so the prompt's local follow-up commands are also source-checkout commands:

node dist/cli.js project prompt --cwd /absolute/path/to/your/repo --source-cli /absolute/path/to/prodex/dist/cli.js

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:

prodex tasks list --status new --cwd /absolute/path/to/your/repo
prodex tasks show <task-id> --cwd /absolute/path/to/your/repo
prodex tasks complete <task-id> --cwd /absolute/path/to/your/repo --summary "prodex MCP verification result" --artifact .bridge/artifacts/results/mcp-verification.md="prodex MCP verification artifact"

After the local completion command succeeds, reply to ChatGPT with local completion done. The generated prompt then asks ChatGPT to call bridge_fetch_result for the same task id, call bridge_fetch_result_artifact for every listed result artifact path, and report whether it can read both the verification result summary and artifact content.

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.

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.

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:

prodex tunnel url --public-url "https://your-tunnel.example" --show-token --url-only

See docs/http-mcp.md for the full ChatGPT Project HTTP MCP setup flow and safety notes.

The MCP write path is intentionally narrow:

  • repo_write_file_dry_run previews an existing repo-relative text-file replacement, stores hashes/diff in a receipt, and stores replacement text under .bridge/artifacts/repo-writes/.
  • repo_write_file_apply applies that receipt only when the current git HEAD and file preimage hash still match.
  • repo_stage_reviewed_paths stages only files whose applied write receipts still match the current git HEAD and file content.
  • 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.
  • No shell execution or direct ungated staging tool is exposed.

For local task-bus smoke tests:

cd /absolute/path/to/your/repo
prodex doctor
prodex tasks create --cwd /absolute/path/to/your/repo --title "Review plan" --prompt "Review this architecture"
prodex tasks list --cwd /absolute/path/to/your/repo
prodex tasks show latest --cwd /absolute/path/to/your/repo
prodex tasks block <task-id> --cwd /absolute/path/to/your/repo --summary "Blocked reason" --code manual_blocker --next-step "What to do next" --retryable
prodex pro ask --dry-run --cwd /absolute/path/to/your/repo --file README.md "Review the project positioning"
prodex sessions list

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.

During local development, you can run the TypeScript source directly:

npm run dev -- tasks list

Claude MCP

If prodex is installed and on your PATH, generate the Claude MCP config JSON:

prodex claude config --cwd /absolute/path/to/your/repo

It prints this token-free config:

{
  "mcpServers": {
    "prodex": {
      "command": "prodex",
      "args": ["mcp", "--cwd", "/absolute/path/to/your/repo"]
    }
  }
}

For a source checkout, first run npm install && npm run build, then generate a node dist/cli.js config:

node dist/cli.js claude config --cwd /absolute/path/to/your/repo --source-cli /absolute/path/to/prodex/dist/cli.js

See docs/claude.md for Claude Desktop and Claude Code notes. Both generated configs point Claude at the same mcp --cwd /absolute/path/to/your/repo server args.

After adding the MCP server in Claude, generate a paste-ready verification prompt:

prodex claude prompt --cwd /absolute/path/to/your/repo

For a source checkout, include the built CLI path:

node dist/cli.js claude prompt --cwd /absolute/path/to/your/repo --source-cli /absolute/path/to/prodex/dist/cli.js

The generated prompt asks Claude to create and read a bridge task only; it does not request write, stage, shell, browser, or tunnel actions. It also includes local claude config --cwd ... and doctor --cwd ... troubleshooting commands in case Claude cannot see or call the MCP tools. Source-checkout prompts keep --source-cli on those troubleshooting commands too.