@cobuild/review-gpt

@cobuild/review-gpt bundles your repo context, opens ChatGPT in a managed Chromium-family browser, and stages a draft with the right review context attached or selected.

It is designed to be installed in any repository that wants a repeatable review:gpt workflow. You keep prompts and presets in the consuming repo, while this package handles packaging, browser automation, response capture, and thread follow-up.

The CLI is implemented with incur, so it also ships with built-in shell completions plus agent-facing --llms, skills add, and mcp add integrations while preserving the existing cobuild-review-gpt command surface.

Skills

This repo also hosts installable Codex skills under skills/.

Current skill:

• work-with-pro: work with a ChatGPT Pro thread for repo tasks. Prefer watch-only when the user already has a prepared thread URL with repo context attached. Default to immediate polling with thread wake --delay 0s --poll-interval 1m, only use a later first check when the user explicitly asks for one, and do not nudge an existing thread unless the user explicitly authorizes that. Use send-and-wake through review-gpt, which owns repo-context packaging. If review-gpt is missing, stop with a clear setup instruction.

Install from the public repo with:

npx skills add https://github.com/cobuildwithus/review-gpt --skill work-with-pro

Why Use It

• turns "open ChatGPT and attach the right repo context" into one command
• packages codebase.zip from your curated repo manifest, can optionally derive a matching Repomix artifact, or can skip file attachments for connector-only review context
• keeps project prompts local to each repo instead of centralizing them in the package
• defaults to draft-only staging, so nothing is sent unless you ask for --send or --wait
• can capture the final assistant response to stdout or a file
• includes delayed send plus thread export, download, and delayed wake helpers for long-running ChatGPT work

Quick Start

Install it in the repo where you want to use it:

pnpm add -D @cobuild/review-gpt

Add a repo-local script:

{
  "scripts": {
    "review:gpt": "cobuild-review-gpt --config scripts/review-gpt.config.sh"
  }
}

Create a shell config that registers the prompts your repo wants to expose:

#!/usr/bin/env bash
browser_binary_path="/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"

review_gpt_register_preset "architecture" "scripts/prompts/architecture.md" \
  "Architecture review with emphasis on boundaries and coupling."
review_gpt_register_preset "bugs" "scripts/prompts/bugs.md" \
  "Behavioral regressions, edge cases, and missing tests." \
  "regressions"
review_gpt_register_preset_group "full-review" "Run the main review passes." \
  "architecture" "bugs"

Then run it:

pnpm review:gpt --preset architecture

On first run with a fresh managed browser profile, sign in to ChatGPT in the opened window once, then rerun the command.

How It Works

Each run can:

• resolve prompt content from repo-local presets plus optional inline --prompt text or --prompt-file
• build codebase.zip from your repo context and, when explicitly enabled, derive repo.repomix.zip or repo.repomix.xml from the same packaged manifest
• skip artifact packaging entirely when --no-artifacts, --no-zip, or attach_artifacts=0 is used
• open ChatGPT and stage a draft with the selected app connector plus any configured repo context URL and file attachments
• optionally auto-submit with --send
• optionally wait for the final response with --wait
• optionally switch into the dedicated Deep Research flow with --deep-research

This package does not own project prompts. Presets, aliases, and preset groups live in the consuming repository, typically through scripts/review-gpt.config.sh.

Credential Safety

Review context is uploaded to ChatGPT, so every packaged ZIP is inspected before it is attached. A run fails with the offending paths listed when the ZIP contains dotenv files (.env, .env.local; .env.example and other *.example/*.sample/*.template/*.dist names are fine), SSH/AWS/GnuPG directories, .npmrc/.netrc/.envrc-style credential files, or private keys and certificates (.pem, .key, .p8, .p12, and similar). Runs also default COBUILD_AUDIT_CONTEXT_EXCLUDE_SENSITIVE=1 for the package script so the @cobuild/repo-tools packager filters the same shapes; set it explicitly to opt out.

Set REVIEW_GPT_ALLOW_SENSITIVE_ARTIFACTS=1 to downgrade the failure to a warning when a match is a false positive.

Common Commands

# Run a named preset
cobuild-review-gpt --config scripts/review-gpt.config.sh --preset architecture

# Schedule a named preset for later
cobuild-review-gpt delay --config scripts/review-gpt.config.sh --delay 50m --preset architecture

# Positional preset shorthand
cobuild-review-gpt architecture --config scripts/review-gpt.config.sh

# Add extra inline instructions
cobuild-review-gpt --config scripts/review-gpt.config.sh \
  --preset bugs \
  --prompt "Focus on auth edge cases and rollback behavior"

# Use a prompt file with the normal repo artifacts attached
cobuild-review-gpt --config scripts/review-gpt.config.sh \
  --prompt-file prompts/release-review.md

# Auto-send and wait for a captured response
cobuild-review-gpt --config scripts/review-gpt.config.sh \
  --wait \
  --response-file review-output.md

# Include or exclude configured test paths
cobuild-review-gpt --config scripts/review-gpt.config.sh --with-tests --preset bugs
cobuild-review-gpt --config scripts/review-gpt.config.sh --no-tests --preset bugs

# Select a ChatGPT app connector before staging the draft
cobuild-review-gpt --config scripts/review-gpt.config.sh --app-connector github --preset architecture

# Use a connector-only review with no artifact files
cobuild-review-gpt --config scripts/review-gpt.config.sh --connector github --no-artifacts --preset architecture

# Deep Research mode
cobuild-review-gpt --config scripts/review-gpt.config.sh --deep-research --wait

# Re-open an existing thread
cobuild-review-gpt --config scripts/review-gpt.config.sh --chat 69a86c41-cca8-8327-975a-1716caa599cf
cobuild-review-gpt --config scripts/review-gpt.config.sh --chat-url https://chatgpt.com/c/69a86c41-cca8-8327-975a-1716caa599cf

Model selection defaults to gpt-5.6-sol, the package alias for ChatGPT's current Pro model. ReviewGPT positively verifies either a selected legacy Pro model row or the current Advanced picker's explicit Model: GPT-5.6 Sol summary and selected model leaf; --model pro targets the same current model. A bare Pro composer pill is treated as an ambiguous Effort summary, so ReviewGPT opens Advanced and verifies the named model instead of accepting that pill as model proof. Model switching leaves the separate Effort control and slider unchanged. Versioned aliases such as gpt-5.5, gpt-5.5-thinking, and gpt-5.5-pro, plus the plain tier aliases instant and thinking, continue to resolve to their supported current picker rows. Plain gpt-5.5 targets the current Instant tier. Non-Pro aliases do not match Pro rows, and obsolete Extended Pro labels are not accepted as current Pro proof. If ChatGPT shows the requested model as disabled, rate-limited, or otherwise unavailable, the run fails with a model-unavailable error instead of silently continuing on the current model. Thinking defaults to current, which is the required setting for normal Pro runs and does not open an independent thinking menu. Explicit xhigh and legacy extended thinking targets are unsupported and fail closed instead of being reinterpreted as a model. Deep Research mode uses the dedicated page and ignores normal model and thinking forcing.

App connector selection defaults to current, which keeps the current ChatGPT composer state. Use --app-connector github or its alias --connector github to open the composer add menu, enter More, and select the GitHub app connector before the prompt and files are staged. Deep Research mode uses its dedicated page and ignores app connector forcing.

Set repo_context_url="https://github.com/owner/repo" in config when connector-only runs should include a specific repository URL in the staged prompt.

Each run stages codebase.zip as the fidelity artifact. Set snapshot_attachment_name="review-gpt.repo-snapshot.zip" in your repo config when a consumer needs a different attachment name. The value must be a .zip filename, not a path.

Repomix is disabled by default. Set repomix_attachment_format="zip" to stage repo.repomix.zip or repomix_attachment_format="xml" to stage the raw XML. The compressed attachment contains repo.repomix.xml at the root of the archive.

Draft staging confirms attachments only after the expected filenames are visible in the ChatGPT composer's own attachment tiles, matched tolerantly against the name(2).ext form ChatGPT gives a repeat upload of the same filename. Hidden file-input state, generic upload UI movement, and prompt text that merely names the artifact are not enough, because none of those leave the model with a readable artifact.

ReviewGPT keeps only one stable local copy of each generated attachment while staging. It removes generated attachments after ChatGPT confirms the send in auto-send mode. Draft-only runs retain them: the draft has not been sent, and deleting a staged file while the browser is still reading it cancels the upload. Dry runs and failed or unconfirmed staging attempts also keep the local artifact for inspection. This cleanup applies only to files generated by ReviewGPT for that run; it never deletes arbitrary user-supplied attachments.

Set attach_artifacts=0, or pass --no-artifacts / --no-zip, to skip the codebase ZIP and any explicitly enabled Repomix artifact. In that mode review-gpt does not run the repo packager.

Repo Configuration

The config file is a sourced shell file that can override defaults, register preset mappings, and adjust path settings.

Optional config override:

snapshot_attachment_name="review-gpt.repo-snapshot.zip"
repomix_attachment_format="xml"   # optional; default is "none"
app_connector="github"            # optional; default is "current"
repo_context_url="https://github.com/owner/repo"
attach_artifacts=0                # optional; default is 1
repomix_ignore_patterns=(
  "dist/**"
  "coverage/**"
)

repomix_attachment_format and repomix_ignore_patterns are opt-in. ReviewGPT builds Repomix from the packaged manifest only when the format is zip or xml; add ignore patterns only when your consuming repo deliberately excludes a subset of those packaged files.

review-gpt packages repo context through its installed @cobuild/repo-tools dependency by default. Keep package_script only for an intentional repo-specific override.

Config helpers exposed by the package:

• review_gpt_register_preset <name> <file> <description> [alias ...]
• review_gpt_register_dir_preset <name> <filename> <description> [alias ...]
• review_gpt_register_preset_group <name> <description> <preset ...>

Each consuming repo must register its own presets. If the config does not register any presets, --list-presets reports none configured and any --preset use fails.

Recommended repo entry point:

{
  "scripts": {
    "review:gpt": "cobuild-review-gpt --config scripts/review-gpt.config.sh"
  }
}

Use the package binary directly. Avoid repo-local wrapper scripts unless you have a concrete repo-specific need beyond passing --config.

The CLI still accepts preset shorthand tokens for the top-level command. cobuild-review-gpt architecture behaves like cobuild-review-gpt --preset architecture, while thread wake ... remains unchanged.

Runtime Extras

In addition to the review workflow, the incur runtime also exposes:

• cobuild-review-gpt completions <bash|zsh|fish>
• cobuild-review-gpt --llms
• cobuild-review-gpt skills add
• cobuild-review-gpt mcp add

Browser Notes

• browser_binary_path is the preferred config knob for the browser executable. browser_chrome_path remains supported for backward compatibility.
• Chromium-family browsers are supported as long as the binary is Chromium-compatible. Chrome, Brave, Chromium, Edge, and Vivaldi all work with the managed-profile launch flow.
• The launcher also checks CHROME_PATH, BROWSER_BINARY_PATH, and --browser-path for one-off browser overrides.
• The managed browser profile defaults to $HOME/.review-gpt/managed-chromium. If an older $HOME/.oracle/remote-chrome profile already exists, the launcher reuses it automatically instead of forcing a new sign-in.
• You can override the managed profile location with managed_browser_user_data_dir and the profile name with managed_browser_profile.
• Managed browsers default to managed_browser_background_mode="balanced": response-polling timers stay unthrottled, while Chromium may deprioritize unrelated renderers and occluded windows. If a specific browser version still freezes background capture, set managed_browser_background_mode="unthrottled" to restore all three legacy backgrounding opt-outs.
• Draft automation creates a fresh ChatGPT browser target for each run and does not foreground the page. If the browser debugging endpoint cannot create a new target, the command fails instead of reusing an existing ChatGPT tab.
• On first run with a fresh managed profile, sign in to ChatGPT in the opened browser window once, then rerun the command.

Response Capture

• --wait implies auto-send and waits up to 120m for the response by default. Browser setup keeps its separate 10m draft timeout (40m in Deep Research mode), so a stalled setup still fails promptly without cutting off a healthy long-running review. Override response capture with --wait-timeout and browser setup with --timeout.
• When --wait is enabled, review-gpt stays attached until the assistant finishes or the wait timeout is hit. Deep Research runs can stay quiet for a long time before the final report arrives.
• A response is only captured after it stays unchanged across consecutive quiet polls (no busy status, no stop control) for several seconds, so interim assistant status messages emitted before long tool/connector work are not mistaken for the final reply.
• Waited runs that request a concrete model require exactly one unfenced, unquoted MODEL_CONFIRMATION line outside rendered quote and code containers in an assistant turn whose immediately preceding user turn is the exact turn committed by this run. An ephemeral per-run nonce at the start of the sent prompt disambiguates concurrent lanes and is the package-owned sentinel that prevents duplicate protocol insertion; ordinary task text cannot suppress the confirmation instructions. The nonce is never written to attestation evidence. A matching textual name passes. UNKNOWN passes immediately when the same assistant snapshot exposes matching ChatGPT response-model metadata, including the gpt-5.6-sol alias's compatible gpt-5-6-pro and gpt-5-6-thinking backend slugs, or after at least 7.5 minutes of observed generation when model metadata is unavailable. This compatibility is directional: selecting Sol/Pro accepts those platform aliases without reinterpreting an explicitly requested Thinking model. Any other present GPT slug mismatch still fails, as do missing or multiple confirmation lines, pre-prompt or concurrently authored turns, named model mismatches, and an unverified UNKNOWN below the elapsed-time threshold. A completed concrete-GPT capture with matching platform metadata emits a versioned REVIEW_GPT_MODEL_VERIFICATION JSON record with requestedModel, responseModelSlug, and responseSha256; the digest covers the exact normalized UTF-8 response-file bytes. The elapsed-time fallback does not claim platform-model evidence. With --response-file, the mandatory response is written atomically with owner-only permissions before completion is emitted. The evidence sidecar is optional: a sidecar-only persistence failure produces a warning, omits the verification record, and never invalidates or repeats the completed response. Exact-target cleanup remains bounded; cleanup uncertainty after a completed capture is reported separately and does not turn that capture into a retryable model failure. A new waited response-file attempt removes only the derived sidecar before browser work, and partial or failed captures never create attestation evidence.
• --response-marker <text> makes capture contract-based instead of heuristic: the wait only accepts a response containing that exact text, so prompts that instruct the assistant to end its final message with the marker are immune to interim status messages even across minutes-long quiet gaps. A marked concrete-model response that completes in under 7.5 minutes fails closed as untrusted even when its model metadata matches; the diagnostic response is still written to --response-file, but no model-verification attestation is emitted. If the marker never appears, capture fails after writing the best snapshot when one was configured.
• Browsers throttle background-tab timers, which can freeze the DOM the capture reads mid-stream. Balanced managed-browser mode keeps those timers reliable while allowing normal renderer and occluded-window scheduling; the capture session pins focus emulation and an active page lifecycle only for its owned page over CDP, then releases emulated focus before retaining or closing the page. Polling therefore works in the background without leaving completed draft or send-without-wait tabs at foreground priority or stealing OS focus.
• Deep Research auto-send gives the product up to 60 seconds to auto-start, then only falls back to the approval-card Start action if that gate is still present.
• Captured assistant output is printed between REVIEW_GPT_RESPONSE_BEGIN and REVIEW_GPT_RESPONSE_END markers so callers can parse it reliably.
• --response-file <path> writes the captured assistant response to a file after the run finishes.

Delayed Runs

Use delay when you want the normal top-level review flow to start later without switching into the thread-wake follow-up workflow.

Examples:

# Schedule a delayed new send
cobuild-review-gpt delay \
  --config scripts/review-gpt.config.sh \
  --delay 50m \
  --preset bugs

# Re-check an existing thread later with the built-in delayed follow-up prompt
cobuild-review-gpt delay \
  --config scripts/review-gpt.config.sh \
  --delay 50m \
  --chat-url https://chatgpt.com/c/69a86c41-cca8-8327-975a-1716caa599cf

Notes:

• delay waits before launching the normal review-gpt review flow. It is for delayed sends or delayed same-thread follow-ups.
• Existing-thread delayed follow-ups default to --wait and to a response file inside output-packages/review-gpt-delay/... unless you override those flags.
• thread wake is different: it revisits an existing thread later, exports the latest assistant text, downloads artifacts from the latest request when they exist, and can hand off into Codex.

Thread Follow-Up

Thread helpers ship through the main CLI:

• cobuild-review-gpt thread export --chat-url <url> --output <path>
• cobuild-review-gpt thread download --chat-url <url> --artifact-index <n> --output-dir <dir>
• cobuild-review-gpt thread diagnose --chat-url <url> --log-file <path> [--receipt-path <path>]
• cobuild-review-gpt thread wake --delay 70m --chat-url <url> --session-id <id>
• cobuild-review-gpt thread wake --detach --delay 0s --poll-interval 1m --chat-url <url> --session-id <id>
• cobuild-review-gpt thread wake --delay 0s --no-poll-until-complete --chat-url <url> --session-id <id>
• cobuild-review-gpt thread wake --delay 0s --poll-interval 1m --poll-jitter 1m --chat-url <url> --session-id <id>
• cobuild-review-gpt thread wake --delay 0s --resume-prompt "<instructions>" --chat-url <url> --session-id <id>
• cobuild-review-gpt thread wake --delay 0s --tab-lifecycle close-created --chat-url <url> --session-id <id>
• cobuild-review-gpt thread wake --delay 0s --recursive-depth 1 --recursive-prompt "<instructions>" --chat-url <url> --session-id <id>
• cobuild-review-gpt thread wake --delay 0s --poll-timeout 120m --recursive-depth 1 --chat-url <url> --session-id <id>

thread export, thread download, thread diagnose, and thread wake require a full ChatGPT conversation URL such as https://chatgpt.com/c/<thread-id>. The plain home URL is rejected before browser automation starts.

For long-running ChatGPT work, these commands read an existing conversation from the same managed Chromium session, retain the latest assistant text response for the latest user request, only accept patch and file artifacts that belong to that latest request, prefer the final assistant turn within that latest request, and can optionally hand off to a follow-up interactive Codex session later.

Examples:

cobuild-review-gpt thread export \
  --chat-url https://chatgpt.com/c/69c71d43-0e38-8330-9df8-c4e10f5bf536 \
  --output output-packages/thread.json

cobuild-review-gpt thread download \
  --chat-url https://chatgpt.com/c/69c71d43-0e38-8330-9df8-c4e10f5bf536 \
  --artifact-index 0 \
  --output-dir output-packages/downloads

cobuild-review-gpt thread diagnose \
  --chat-url https://chatgpt.com/c/69c71d43-0e38-8330-9df8-c4e10f5bf536 \
  --log-file output-packages/chatgpt-watch/run/recursive-review-send.log \
  --receipt-path output-packages/chatgpt-watch/run/recursive-followup.json

cobuild-review-gpt thread wake \
  --delay 70m \
  --chat-url https://chatgpt.com/c/69c71d43-0e38-8330-9df8-c4e10f5bf536 \
  --session-id 019d36e3-f6a2-7873-910a-2bdbd4f9748c

cobuild-review-gpt thread wake \
  --delay 0s \
  --poll-interval 1m \
  --poll-jitter 1m \
  --chat-url https://chatgpt.com/c/69c71d43-0e38-8330-9df8-c4e10f5bf536 \
  --session-id 019d36e3-f6a2-7873-910a-2bdbd4f9748c

cobuild-review-gpt thread wake \
  --delay 0s \
  --no-poll-until-complete \
  --chat-url https://chatgpt.com/c/69c71d43-0e38-8330-9df8-c4e10f5bf536 \
  --session-id 019d36e3-f6a2-7873-910a-2bdbd4f9748c

cobuild-review-gpt thread wake \
  --delay 0s \
  --chat-url https://chatgpt.com/c/69c71d43-0e38-8330-9df8-c4e10f5bf536 \
  --session-id 019d36e3-f6a2-7873-910a-2bdbd4f9748c \
  --tab-lifecycle close-created

cobuild-review-gpt thread wake \
  --delay 0s \
  --chat-url https://chatgpt.com/c/69c71d43-0e38-8330-9df8-c4e10f5bf536 \
  --session-id 019d36e3-f6a2-7873-910a-2bdbd4f9748c \
  --resume-prompt "After applying the returned patch, run pnpm review:gpt --send --chat-url {{chat_url}} and ask for final bug and simplification feedback."

cobuild-review-gpt thread wake \
  --delay 0s \
  --poll-interval 1m \
  --poll-timeout 120m \
  --chat-url https://chatgpt.com/c/69c71d43-0e38-8330-9df8-c4e10f5bf536 \
  --session-id 019d36e3-f6a2-7873-910a-2bdbd4f9748c \
  --recursive-depth 1

cobuild-review-gpt thread wake \
  --delay 0s \
  --chat-url https://chatgpt.com/c/69c71d43-0e38-8330-9df8-c4e10f5bf536 \
  --session-id 019d36e3-f6a2-7873-910a-2bdbd4f9748c \
  --recursive-depth 1 \
  --recursive-prompt "Wait for the thread response, then implement the returned plan as a clean long-term patch with tests and return a .patch attachment."

Resume notes:

• cobuild-review-gpt thread wake does not touch the managed browser until the configured --delay has elapsed, so scheduling a 60m or 100m follow-up does not immediately reopen or navigate the ChatGPT tab.
• --detach launches the wake loop as its own background process, writes wake.log beside status.json, and returns immediately with the detached PID plus output paths. Use it when the current shell, terminal, parent agent, or PTY may exit before the wake finishes.
• Polling is enabled by default. After the initial delay, thread wake always forces one same-tab reload before the first export so stale hydrated ChatGPT state cannot masquerade as a fresh thread, then keeps re-exporting until it sees a stable final state: assistant-owned artifacts end the wait immediately, while no-artifact replies must stay unchanged across consecutive idle polls after ChatGPT no longer exposes busy status or stop controls. Wake reuses the current same-thread tab when one already exists. If it must create a tab, --tab-lifecycle close-created closes only tabs created by that wake run after each export/download; the default keep preserves legacy behavior. --poll-interval defaults to 1m, --poll-jitter defaults to 1m so the normal retry cadence lands between 60 and 120 seconds, and polling also adds a small hidden startup spread before the first export so several simultaneous wake runs do not all hit ChatGPT at once. --poll-timeout can bound that wait, and --no-poll-until-complete restores the old one-shot behavior.
• Wake treats ChatGPT's own visible assistant failure controls, such as Thinking failed or Stopped thinking, as terminal generation failures instead of retaining them as prose-only responses.
• Every successful wake export writes assistant-response.md and assistant-response.meta.json beside thread.json, even when artifacts are also downloaded. Prose-only replies can hand off to Codex from this retained response file without needing a .patch or .diff attachment.
• Polling tolerates a few transient thread-export failures before the first successful snapshot, and after a good snapshot exists it keeps polling until the overall timeout instead of aborting immediately on a short flaky stretch.
• Wake records the last assistant preview, busy reason, retained text response paths, artifact labels, and download outcomes in status.json for debugging.
• thread wake reuses an existing tab only when it is already on the same /c/<thread-id> conversation, and treats same-thread URLs with extra query parameters as the same thread.
• After the delay elapses, thread export inspects the current ChatGPT tab first, only navigates or reloads when needed, and still requires real conversation signals before capture so generic ChatGPT chrome does not masquerade as a ready thread. Thread download keeps the hydrated thread tab alive and activates the visible attachment control inside the page before falling back to a native browser click.
• Thread export and download scope artifact discovery to the conversation body, ignore ChatGPT conversation links that only look like attachments, and only consider assistant-owned downloadable controls that appear after the latest user message in the thread. Within that latest request, they prefer the final assistant turn, download every assistant-owned final-turn control by artifact index instead of gating on patch-shaped labels, and still carry forward human-readable artifact labels for wake/debug handoff when ChatGPT exposes them.
• Thread export now preserves the full assistant turn text in saved snapshots instead of clipping assistant messages to a 20k-character preview.
• thread download still honors native browser downloads when ChatGPT emits them, but it also falls back to authenticated estuary fetches for inline assistant download controls such as combined patch buttons and native-download cases where the browser never materializes the file on disk. Failed native-download attempts clean up zero-byte files they created, and thread wake retries each artifact download once before recording a final download error.
• cobuild-review-gpt thread wake resolves the local codex executable itself, so launchd, tmux, nohup, and similar runs do not depend on your interactive shell PATH.
• cobuild-review-gpt thread wake captures the current working directory and launches a fresh codex exec child with -C set to that repo directory, seeded with the built-in wake prompt, the exported thread JSON, the retained assistant text response, and every downloaded assistant artifact from the latest request.
• Wake now launches the follow-up through codex exec --json with CODEX_HOME pinned to the resolved owner home, so the prompt is submitted directly without PTY keystroke injection.
• Wake verifies launch from the child JSON event stream, then records childSessionId, childSessionPersistence, childRolloutPath, launcherPid, eventsPath, resumeOutputPath, and stderrPath in status.json for debugging. childSessionPersistence: "pending" means the child already started but the resolved CODEX_HOME had not exposed shell/history/session-log evidence yet.
• Once that follow-up Codex session is verified and handed off successfully, thread wake writes state: "succeeded" and exits instead of waiting for the spawned Codex run to finish.
• The built-in wake prompt always includes the watched ChatGPT thread URL so the resumed Codex session can reuse it for follow-up review:gpt --send commands.
• thread diagnose captures a structured failure bundle for same-thread send and wake problems: matching managed-browser tabs, which tab selection would currently win, a sanitized command log copy, an optional sanitized recursive receipt copy, and a fresh sanitized thread export under output-packages/review-gpt-diagnostics/.
• --recursive-depth <n> adds a built-in same-thread review loop on top of the normal wake handoff. When n > 0, wake now generates recursive-followup.sh inside the wake output directory. The resumed child runs that helper after verification; it sends the built-in bug-and-simplification review with an explicit 300s timeout, writes recursive-followup.json plus recursive-review-send.log, and, on success, arms one more detached thread wake on the same URL with the counter decremented. When the counter reaches 0, the next child applies the returned review patch and stops.
• Top-level auto-send on an existing conversation now auto-captures the same diagnostics bundle on managed-browser send failure, and recursive same-thread follow-up helpers do the same automatically before they exit non-zero. Recursive receipts now record the diagnostics output and status paths.
• --recursive-prompt overrides that built-in same-thread review prompt. The same override is baked into recursive-followup.sh and forwarded to descendant recursive wakes so one custom recursive workflow can run across the whole chain.
• Recursive wakes now use deterministic nested output directories such as recursive-depth-0 under the current wake directory instead of scattering timestamped descendant runs elsewhere. status.json records the generated recursive helper paths and the expected descendant status.json path so second-hop debugging does not require filesystem scanning.
• Wake also writes wake-commands.sh beside thread.json and status.json; those direct node .../bin.mjs thread export|download commands bypass pnpm exec, so a stale consumer workspace install does not block thread re-export or attachment re-download during follow-up debugging.
• --resume-prompt appends extra instructions to the built-in Codex wake prompt instead of replacing the default export/download/apply guidance, and supports {{chat_url}} plus {{chat_id}} placeholders for the watched thread.
• Auto-send now re-checks the final composer and thread state once more before declaring commit-timeout, so ambiguous send confirmations do not break recursive wake chains when the message actually landed.
• If you omit --codex-home, the wake command searches CODEX_HOME, ~/.codex, and ~/.codex-* homes for evidence of the target session ID and refuses to resume if more than one home matches.
• If you already know the owner home, pass --codex-home <path> to skip discovery and make the resume target explicit.
• The supplied --session-id is only used to discover the owning CODEX_HOME; wake then starts a fresh interactive session in that same home instead of mutating the original session ID.
• --full-auto is now opt-in on thread wake; without it, the launched Codex session behaves like a normal manual interactive launch.
• Wake stores the exported thread, all downloaded assistant artifacts, wake-commands.sh, and status.json alongside the follow-up launch.
• --skip-resume still exports the thread and downloads any assistant-owned artifacts, but it does not launch the follow-up Codex session.
• If you do not use --detach, keep long wake runs under nohup, tmux, screen, launchd, or another supervisor so the foreground wake process survives terminal exit.

Local Package Iteration

For local package iteration, prefer package-manager linking or a local file dependency rather than wrapper-script fallbacks:

pnpm add -D file:../review-gpt
# or
pnpm link --global ../review-gpt
pnpm link --global @cobuild/review-gpt

Release

This package is published as @cobuild/review-gpt on npm.

Release ownership note: release, version-bump, and publish actions are user-operated by default. Agents should not run release flows unless explicitly instructed in the current chat turn.

pnpm run release:check
pnpm run release:dry-run
pnpm run release:patch
# or: pnpm run release:minor
# or: pnpm run release:major
# or: pnpm run release:alpha

The local release script:

• requires a clean git working tree on main
• verifies package scope @cobuild/review-gpt
• supports check, pre* bumps with --preid, and strict exact semver input
• uses pnpm versioning so pnpm-lock.yaml stays authoritative and package-lock.json is not recreated
• bumps version and updates CHANGELOG.md
• creates release commit release: v<version>, tags v<version>, and pushes main plus tags
• after push, waits for npm publish visibility and then attempts to update sibling repos under the configured sync root that depend directly on @cobuild/review-gpt

Release helpers resolve @cobuild/repo-tools from the installed dependency in node_modules first and fall back to the sibling repo-tools checkout in this workspace when testing unreleased shared tooling before the next publish.

If downstream sync fails after a successful publish, the release command now warns and exits successfully so a completed publish is not misreported as a failed release. You can rerun the sync manually.

You can skip the post-release sibling sync with --no-sync-upstreams or REVIEW_GPT_SKIP_UPSTREAM_SYNC=1.

Manual sync command:

pnpm run sync:repos -- --version "$(node -p "require('./package.json').version")" --wait-for-publish

Publishing is tag-driven in GitHub Actions at .github/workflows/release.yml:

• validates tag format and version match with package.json
• runs tests and checks, creates a tarball, and creates a GitHub Release with Codex-style notes
• publishes to npm via Trusted Publishing, including prerelease channel tags such as alpha, beta, and rc

Before first automated publish, configure npm Trusted Publisher for @cobuild/review-gpt to allow cobuildwithus/review-gpt GitHub Actions to publish.

Changelog helpers:

pnpm run changelog:update -- 0.1.1
pnpm run release:notes -- 0.1.1 /tmp/release-notes.md