Release notes

This page follows Keep a Changelog and Semantic Versioning. The repository's CHANGELOG.md is the English source.

0.3.0-rc.3 (November 10, 2026)

First release.

Added

• Run through your package manager. Set up a project with npx review-bridge init; no global install is required. A global install with npm i -g review-bridge also works. Bridge prints commands using the package manager that launched it: npx review-bridge … for npm or when no package manager is specified, pnpm dlx review-bridge …, yarn dlx review-bridge …, or bun x review-bridge …. Commands omit the version and use the published latest release; npx uses a global installation when one is present. This applies to setup instructions, status output, suggested next commands, agent entry points, and VS Code tasks. Only --help uses the bare program name. Requires Node.js 22.8 or newer.
• Interactive setup. Following create-vite's approach, init asks for a writer, reviewer, project type, and optional VS Code tasks, with a default for each. It then sets up the current folder, prints progress one step per line, and shows the next commands. There is no extra confirmation or plan preview. Options supply answers directly; without an interactive terminal, defaults are used. The project type selects the test command and can be none.
• Project files stay contained. Except for VS Code tasks you opt in to, init writes only to .review-bridge/: settings, rules, and work-order templates. Its own .gitignore contains *, keeping the folder out of Git even if you initialize Git later. Setup leaves git status clean and doesn't modify the project's .claude/, AGENTS.md, or CLAUDE.md.
• User-level agent entry points. init installs ~/.claude/commands/review-bridge.md for Claude Code, respecting CLAUDE_CONFIG_DIR, and ~/.agents/skills/review-bridge/SKILL.md for Codex. /review-bridge and $review-bridge teach the agent four actions—start, stop, resume, and clean—and require a person's approval. Existing user files at those paths are left alone. Uninstalling the last configured project removes Bridge's entries unless you've edited them.
• A project graph for code navigation. init records definitions, name references, and import destinations in your database for JavaScript, TypeScript, .vue script blocks, Python, Go, Rust, Java, Kotlin, C++, and C#. Progress output ends with file, definition, reference, and import counts, plus a list of files that couldn't be fully parsed. No graph files are written to the project. Parsers for languages other than JavaScript and TypeScript are installed through npm into Bridge's data directory on first use. In npm and pnpm workspaces, the graph covers the package and its workspace dependencies. start refreshes only files Git reports as changed; npx review-bridge graph rebuilds the full graph. Writer and reviewer can query it through Bridge's read-only MCP server, review-bridge-graph.
• Contract creation without model calls. Bridge validates the work order as a form and copies each marked block into the contract unchanged. The result's token table records 0 tokens for this step. Acceptance lists are parsed with markdown-it, as in VitePress. Work orders require work instructions (requested_work or run_plan) and an acceptance list. Missing required content, invalid list items such as 一、 or （1）, and unanswered open questions stop start before the card. Bridge lists the problems and restores any missing required block marker and heading at the end of the file, leaving existing text unchanged. A # title is optional; without one, the title is untitled.
• Per-role model and effort settings. Work-order frontmatter accepts writer: and reviewer: blocks with model and effort, overriding the policy's priority table. Top-level effort applies to the writer; specifying both forms is rejected. model: null, the default for both roles, uses the CLI's default. A model that doesn't match its role's CLI is rejected before the card.
• One card and one approval to start. npx review-bridge start <file> plans the work and shows a card identifying the contract. In a terminal, it asks Start this work? [y/N] and prints one line per step. Without an interactive terminal, start and resume show the card and stop at Needs authorization. After you approve, the agent reruns the command with --yes. Authorization records authorized_via (terminal or agent) and the SHA-256 of the sealed work-order text. --yes uses the previously displayed card's plan. It is rejected if no card was shown, the work order or options have changed, the card has passed its Valid until time, or the card has already started a run. A rejected request authorizes and starts nothing. Each rejection includes the next command to run.
• Work-order identity and version history. On first approval, Bridge writes an id into the work order's frontmatter and records its versions in the database. Renaming or moving a file preserves its identity; editing its text creates a new version. A copy containing another file's ID gets its own, while two hard links to the same file remain one work order. Filesystems that don't provide file IDs are rejected. File names support letters, digits, and combining marks from any script, plus ., _, -, and single spaces, up to 80 characters and 180 bytes. Names are normalized to NFC for comparison and storage. The card identifies the work order being authorized; --update <work_order_id> and --as-new let you specify a different identity choice.
• Run work orders in sequence. start <directory> treats a subdirectory of .review-bridge/work-packages/ as a pipeline. Files run in name order, using numeric prefixes such as 01- and 02_, with unnumbered files last. Bridge checks the whole directory and shows one card listing the files without their contents. One approval authorizes the pipeline, with a separate run, authorization record, and contract for each work order. A failed work order doesn't stop the next one. A provider sign-out, exhausted quota, stop, or Ctrl+C stops the pipeline. Work orders recorded as delivered are skipped when you start again. status shows progress, a final table summarizes the results, and files go under results/<directory>/<work order>/.
• Stop, resume, and clean. stop <run_id> pauses a run and preserves its records. resume <run_id> starts a new run with the same stopping point and scope. clean [<run_id>] clears finished records; clean --all clears the project's records from the database.
• Choose either provider for either role. Writer and reviewer support all four pairings of claude and codex, with separate sessions. Roles come from bridge.json or per-run --writer and --reviewer options on start, resume, and work-plan. The card shows the selected roles, which stay fixed for that run. Each run record and result header include both roles' provider, model, and effort.
• Read-only reviewer checks. Before model work begins, Bridge verifies the reviewer's restrictions. For Codex, its OS sandbox must deny an actual write; the check also recognizes PowerShell's denial messages on Chinese-language Windows. For Claude Code, a plan-mode session with only Read, Grep, Glob, and Bridge's graph server plus policy-approved servers is asked to write a sentinel file. The check passes only if the file is absent, the CLI finishes, and its init event confirms the expected session configuration.
• Personal connector isolation. Every Claude Code call uses --strict-mcp-config; only the writer receives the project's .mcp.json. Every Codex call uses --disable apps --disable plugins and disables each MCP server named by codex mcp list. If that list can't be read, work doesn't start. The policy's reviewer.mcp_allow, empty by default, passes named servers to the reviewer without additional restrictions. The card, run record, and result list the servers provided.
• Verification run by Bridge. After each writer call, Bridge runs the project's test command itself. Projects without a test command can still run; the card, records, and result state that tests aren't configured. When the project has a test command, a writer reporting blocked without asking a question still proceeds to Bridge's test step and review; without one, the run stops and returns to you.
• Writer token budgets. tokens and tokens_per_call apply to the writer and exclude cache reads, which are listed separately in the result. Reviewer usage is recorded but doesn't count against a token budget.
• Results with supporting records. Each run produces a result file under results/<work order>/ explaining what was decided and why. Results needing your decision include the writer's own explanation. Files changed separates Git changes, the writer's unverified change report, and changes that existed before the run.
• An audit trail in PostgreSQL. One embedded PostgreSQL 18 database per user stores work orders, versions, cards, authorizations, contracts, runs, sequenced events, reviewer verdicts, Bridge's acceptance decisions, and deliveries across projects. It is created on first use. Each state change and its event are committed in the same transaction. clean <run_id> deletes the run and its dependent records together, while preserving the consumed authorization so the card can't be reused. Files under .review-bridge/ and logs are copies.
• Database lifecycle controls. The database keeps running after you close the terminal or VS Code. up starts the database, then the local page; down stops them in reverse order, following the docker compose down convention of stopping what up started. If any project has an active run, down lists the runs and refuses to stop. status reports database state without starting it. A missing, unreadable, or invalid data directory is reported with its path, using exit code 4 as pg_ctl status does. Startup failures include how long pg_ctl waited and the latest server message. Startup doesn't clear files left by a dead server; if its processes are still running, Bridge reports that and asks you to restart the computer.
• Backups before migrations. Before a new version applies database migrations, its first command backs up the database and prints the backup location. Backups are refused while a run is active. If the database contains migrations unknown to the installed version, Bridge names them, refuses to open it, and makes no changes. Use backup to create a backup manually when no runs are active.
• Stop on database loss. If the database becomes unavailable during a run, it stops with database_unavailable and makes no further model calls. Records collected in the meantime are written back by the next command that opens the database.
• Queryable run status. status, work-status, and doctor read database records showing the page, run status, stop reason, source file, and start time. Results are paginated in groups of ten; use --after <run_id> for the next page or --json for machine-readable output. status also prints the host, port, database, user, and password-file location for connections from VS Code's PostgreSQL extension or SQLTools.
• Localized CLI output. init, status, up, down, ps, and the authorization card use the project's language, English or Traditional Chinese, detected from the system using create-vue's approach.
• VS Code tasks. Run start, stop, resume, clean, status, and logs from Quick Open by typing task review-bridge. Opt in to the project's .vscode/tasks.json during init, add tasks later with npx review-bridge vscode, or use npx review-bridge vscode --user for user-level tasks. The default is not to add project tasks. Other tasks, comments, and formatting are preserved; uninstall removes only Bridge's entries.
• Windows encoding diagnostics. doctor reports when PowerShell isn't writing UTF-8, which can garble Codex's Chinese output, and shows the line to add to $PROFILE.
• Generated command help. Every command has --help generated from the command table, including option types, defaults, and descriptions. --help --all also lists commands for agents and scripts, such as work-plan and work-start. --version prints the version.

Known limitations

• On Windows, two simultaneous --yes requests for one card can cause the second to return a file error instead of reporting that the card was used. Only one run starts. Approve each card once.
• With Git's core.autocrlf on Windows, line-ending-only changes count as changes in work proof and results. Commit or stash before start.
• The writer doesn't pause to ask questions during implementation. Resolve ambiguities in the work order before start; an unanswered line in open_questions prevents it from starting.
• The writer may run or edit your project's tests. Bridge doesn't block or flag this. Test evidence in the result comes from Bridge's own test run after each writer call. Review the changed files listed in the result.
• Running through npx checks the npm registry for the latest version and requires network access. A global install with npm i -g review-bridge avoids that lookup; npx review-bridge then uses the installed copy.
• Ctrl+C during a single-file start in a terminal ends the command, but the run may continue. Find it with npx review-bridge status, then stop it with npx review-bridge stop <run_id>.
• In the runs measured for this release, neither the writer nor the reviewer called the project-graph tools on its own.
• Some messages from commands for agents and scripts, including work-plan and work-start, aren't localized.
• The card's Valid until time is displayed in UTC.
• The final output line doesn't include the run ID. Use npx review-bridge status to find it.
• Directory pipelines run in the project folder. Starting two directories at once makes them share that folder; wait for one to finish before starting the next.
• vscode isn't listed in npx review-bridge --help. Use npx review-bridge vscode --help for its options.
• Work proof compares the project only at Bridge's sampling points. A file changed and restored between checks won't appear as changed.
• Native execution is verified on Windows x64. Apple Silicon macOS is selectable but unverified. Linux blocks native execution.
• Upgrading to a different PostgreSQL major version requires a dump and restore, which this version doesn't handle.