@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 artifacts already attached.

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 a snapshot ZIP from your curated repo manifest and can optionally derive a matching repomix artifact from that same manifest
• 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 a snapshot ZIP from your repo context and, unless disabled, derive repo.repomix.zip or repo.repomix.xml from the same packaged manifest
• open ChatGPT and stage a draft with the repomix artifact first when enabled and the snapshot ZIP attached after it
• 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.

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

# 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.5-pro. Use --model to override it. Versioned aliases such as gpt-5.5, gpt-5.5-thinking, gpt-5.5-pro, and the plain tier aliases instant, thinking, and pro still resolve correctly even when the ChatGPT picker currently shows generic rows like Thinking, Instant, Pro Extended, or the composer chip label Extended Pro. Plain gpt-5.5 targets the current Instant tier. Non-Pro aliases do not match Pro or Extended Pro rows. Thinking defaults to current. 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.

Each run stages a snapshot ZIP as the fidelity artifact. The default filename is repo.snapshot.zip; set snapshot_attachment_name="review-gpt.repo-snapshot.zip" in your repo config when a consumer needs a more specific attachment name. The value must be a .zip filename, not a path.

By default, each run also stages repo.repomix.zip, derived from the same packaged manifest, as the compact review artifact. The compressed Repomix attachment contains repo.repomix.xml at the root of the archive. Set repomix_attachment_format="xml" in your repo config if you need the raw XML attachment instead, or repomix_attachment_format="none" if your repo wants to skip repomix entirely.

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"   # default is "zip"; use "none" to disable repomix
app_connector="github"            # optional; default is "current"
repomix_ignore_patterns=(
  "dist/**"
  "coverage/**"
)

repomix_ignore_patterns is opt-in. review-gpt already builds repomix from the packaged manifest, so only add ignore patterns when your consuming repo has a deliberate reason to exclude a subset of those packaged files from repomix.

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.
• 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 uses a longer timeout budget: 10m by default and 40m in Deep Research mode.
• 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.
• 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, 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 0.2.9 --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