Running and packaging
This page is for running Co-Review from a clone of the repository, and for building the desktop app and its installers. To just use Co-Review, the install script is quicker.
Requirements
Section titled “Requirements”- Node.js 20 or later (tested with 24), npm and Git.
- A C/C++ toolchain for native modules: the Xcode command-line tools on macOS,
build-essentialon Linux. - Network access to npm, Open VSX (plugins) and GitHub (Electron) for the first install.
Then install the dependencies:
# npm install, plus the VS Code built-in plugins (Git, languages) into plugins/make install
# list every targetmake helpBrowser app
Section titled “Browser app”Build Co-Review and open a repository in your browser:
# builds, starts on http://127.0.0.1:3000 in the background, opens the browsermake start REPO=/path/to/repo
# the same, on another portmake start REPO=/path/to/repo PORT=4000make start runs bin/co-review.mjs. It starts the server in the background, or reuses one that is already
running, and opens http://127.0.0.1:<port>/#<repo>. The server log is ~/.co-review/server.log.
One server serves any number of repositories. To open another one:
node bin/co-review.mjs /other/repoTo stop the server:
kill $(jq .pid ~/.co-review/server.json)(or pkill -f applications/browser/lib/backend/main.js).
Development. make dev recompiles the extension and rebundles the frontend whenever a file changes. Reload
the browser to see frontend changes; restart the server for backend changes.
Desktop app
Section titled “Desktop app”# build and run the Electron appmake desktop REPO=/path/to/repo
# installers for this OS, in applications/electron/distmake package
# the unpacked app only (faster)make package-dirWhat make package produces (configured in applications/electron/electron-builder.yml):
| OS | Output |
|---|---|
| macOS | dmg and zip |
| Linux | AppImage and deb |
| Windows | nsis installer |
Signing. Builds are unsigned, so on macOS open an unsigned build with right-click → Open the first time. To
sign on macOS, set CSC_LINK and CSC_KEY_PASSWORD and remove identity: null. To notarize, also set APPLE_ID,
APPLE_APP_SPECIFIC_PASSWORD and APPLE_TEAM_ID.
What’s in the package:
- The built frontend and backend (
lib/,src-gen/) and the productionnode_modules. - The VS Code built-in plugins (
plugins/, loaded byscripts/electron-main.js). Built-ins that aren’t needed (debugger, notebooks, Emmet, extra themes, …) are listed undertheiaPluginsExcludeIdsin the rootpackage.json. - The agent integrations the app installs for you: the Claude Code plugin (
plugin/,.claude-plugin/), the Pi and Oh My Pi packages (integrations/pi,integrations/omp, sharingintegrations/shared) and theco-reviewcommand (bin/).
Releases
Section titled “Releases”.github/workflows/release.yml builds the app for macOS (arm64), Linux (x64, arm64) and Windows (x64). For a v*
tag, it also publishes a GitHub release.
To release, bump the version everywhere it is recorded (the app, the review extension, the Claude Code plugin
manifests and the Pi/omp packages), then tag and push. make check-versions (part of make test) fails when any of
them differs from extensions/review/package.json, and the workflow fails when the tag differs too:
git tag v0.2.0 && git push origin v0.2.0To get the builds as artifacts without releasing, run the workflow by hand: Actions → Release → Run workflow.
Asset names carry no version (Co-Review-mac-arm64.zip, Co-Review-linux-x64.tar.gz, Co-Review-win-x64.exe,
…). That way install.sh can always download releases/latest/download/<name>:
curl -fsSL https://sdsvn.github.io/co-review/install.sh | bashAn update usually downloads about a tenth of the app. Most of the app is Electron (about 110 MB of a 150 MB
download), and it rarely changes between releases. So for macOS and Linux the release also publishes the app folder
on its own (Co-Review-<os>-<arch>-app.tar.xz, about 15 MB) and what surrounds it
(Co-Review-<os>-<arch>-runtime.txt: the Electron version and a hash of electron-builder.yml and the icons, from
bin/runtime-key.mjs). The same line ships inside the app as runtime.txt. When the installed one matches the
release’s, install.sh replaces only the app folder (and the bundle’s version on macOS). Otherwise it downloads
the whole app, as it does for a new install, CO_REVIEW_FORCE=1, an install from before 0.9.2 and Windows.
After installing (or finding that version already installed), install.sh brings the agent integrations that are
already installed to the app’s version: the Claude Code plugin (claude plugin marketplace update co-review, then
claude plugin update co-review@co-review), and the Oh My Pi and Pi packages when they come from this app
(omp install / pi install of its integrations/ path, which refreshes the version they recorded). It skips a
harness or plugin that isn’t installed and never fails the install over them.
An update stops the Co-Review that is running, three ways, so an old version never keeps serving the new
command and agents (its files replaced under it, macOS kills its helper processes but not the app, which then
holds the single-instance lock: nothing can start). install.sh and make install-app quit it before replacing
its files; the running app quits itself once the version on disk is not its own, or once its backend is gone;
and the co-review command stops a running app of another version, or one without a backend, before starting
one (co-review logs shows each as “stopping Co-Review (process …)”). Reviews are saved; the next
co-review call starts the new version.
Installing on macOS
Section titled “Installing on macOS”# package, copy Co-Review.app to /Applications (or ~/Applications),# and install the co-review commandmake install-appThe co-review command is a small shim that bin/install-cli.sh writes to /usr/local/bin when it is
writable, otherwise to ~/.local/bin. Set PREFIX=… to choose another place.
co-review [dir]opensdirin the desktop app, or focuses its window if it is already open.co-review mcp [dir]connects an agent (stdio MCP) to the app’s backend, found through~/.co-review/server.json. It starts the app on the agent’s first tool call, not when the agent session starts, and in the background: no window until the agent shows a review (open_review), or you open the app. A window the agent showed closes when the agent is done with the review (you submit it, or its session ends): it says why and closes after 10 seconds unless you keep it open; with no window left the app quits. Closing a window yourself is told to the agent. If Co-Review goes away mid-session, the agent’s call fails instead of waiting, and its next call starts Co-Review again.co-review status [dir]prints this Co-Review’s version and each installed agent integration’s (the Claude Code plugin, the Oh My Pi and Pi packages), flags any that differ with the command that updates it, then lists the open reviews ofdirin a running Co-Review (it never starts one).co-review setup <pi|omp>installs the Pi or Oh My Pi package that ships with the app.co-review logsis for when something hangs or fails: whether Co-Review answers (and how fast), then the recent debug log of every Co-Review process merged by time (--lines <n>, default 80). The logs are in~/.co-review/logs:main.log(the desktop app’s windows: not responding, page crashes, errors in a window’s console),backend.log(the backend, including when it was blocked for over a second) andcli.log(theco-reviewcommand and each agent’sco-review mcpbridge).co-review version(-v) prints the version;co-review help(-h) lists the commands and options.
Installed from the app, the shim runs bin/co-review.mjs inside the app bundle, on the app’s own Electron
(ELECTRON_RUN_AS_NODE=1). Installed from a checkout (make install-cli), it runs on node and starts the
browser app instead.
Security. The desktop backend only accepts its own windows (Theia’s per-launch token). Two endpoints are
exempt, /mcp and the phone view (src/electron-node), and they only accept local connections. /mcp also
refuses browser requests from other origins.
Environment and language servers
Section titled “Environment and language servers”Environment. An app opened from Finder or the Dock gets a minimal environment on macOS, without your shell’s
PATH. So at startup, scripts/electron-main.js reads your login shell’s environment ($SHELL -ilc env). That
way gopls, other language servers and ACP agents are found just as in a terminal.
- Launched from a terminal (
co-review,make desktop), the app keeps that terminal’s environment. - Set
CO_REVIEW_NO_SHELL_ENV=1to skip reading the shell environment.
Language servers. Go to definition, find references and the like come from VS Code extensions. They are listed
in theiaPlugins in the root package.json and downloaded into plugins/ by make plugins.
- Included: the built-ins (TypeScript/JavaScript, JSON, PHP; Markdown renders in Co-Review’s own view, VS Code’s Markdown preview is excluded) and
golang.Go, which needsgopls. - For other languages, add an Open VSX extension to that list.
- Language servers only start in trusted workspaces.
Native modules
Section titled “Native modules”node-pty, drivelist, keytar and native-keymap are compiled against Node for the browser app, and against
Electron for the desktop app. make browser and make desktop-build switch between the two (theia rebuild:browser|electron, with the originals cached in .browser_modules/). So build the target you run last.
Configuration
Section titled “Configuration”| Variable | Default | Meaning |
|---|---|---|
CO_REVIEW_HOME |
~/.co-review |
Review storage, server registry (server.json), server log |
CO_REVIEW_PORT |
3000 |
Port for co-review / co-review mcp when starting the browser app |
CO_REVIEW_ALLOWED_HOSTS |
— | Comma-separated extra host names allowed to open the phone view (/m/) |
Agents launched over ACP inherit the environment of the Co-Review process. So start Co-Review from a shell where the agent is logged in and configured.
Co-Review ships Co-Review Dark and Co-Review Light themes and follows the OS setting. Switch with Preferences: Color Theme.
Phone view
Section titled “Phone view”/m/ on the running app (browser app or desktop backend) is a small page for reviewing away from your desk. You
can install it on your phone’s home screen. It has:
- the review list, and the threads with their replies;
- Resolve, and Accept / Dismiss for findings and suggestions;
- Submit review.
It updates live (long polling). Only local connections are allowed, so to reach it from a phone:
-
Expose the port on your Tailscale network:
Terminal window tailscale serve --bg 3000 -
Start Co-Review with that host name allowed:
Terminal window CO_REVIEW_ALLOWED_HOSTS=my-mac.tailnet-name.ts.net make start -
On the phone, open
https://my-mac.tailnet-name.ts.net/m/and choose Add to Home Screen.