Skip to content

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.

  • 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-essential on Linux.
  • Network access to npm, Open VSX (plugins) and GitHub (Electron) for the first install.

Then install the dependencies:

Terminal window
# npm install, plus the VS Code built-in plugins (Git, languages) into plugins/
make install
# list every target
make help

Build Co-Review and open a repository in your browser:

Terminal window
# builds, starts on http://127.0.0.1:3000 in the background, opens the browser
make start REPO=/path/to/repo
# the same, on another port
make start REPO=/path/to/repo PORT=4000

make 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:

Terminal window
node bin/co-review.mjs /other/repo

To stop the server:

Terminal window
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.

Terminal window
# build and run the Electron app
make desktop REPO=/path/to/repo
# installers for this OS, in applications/electron/dist
make package
# the unpacked app only (faster)
make package-dir

What 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 production node_modules.
  • The VS Code built-in plugins (plugins/, loaded by scripts/electron-main.js). Built-ins that aren’t needed (debugger, notebooks, Emmet, extra themes, …) are listed under theiaPluginsExcludeIds in the root package.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, sharing integrations/shared) and the co-review command (bin/).

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

Terminal window
git tag v0.2.0 && git push origin v0.2.0

To 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>:

Terminal window
curl -fsSL https://sdsvn.github.io/co-review/install.sh | bash

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

Terminal window
# package, copy Co-Review.app to /Applications (or ~/Applications),
# and install the co-review command
make install-app

The 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] opens dir in 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 of dir in 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 logs is 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) and cli.log (the co-review command and each agent’s co-review mcp bridge).
  • 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. 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=1 to 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 needs gopls.
  • For other languages, add an Open VSX extension to that list.
  • Language servers only start in trusted workspaces.

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.

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.

/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:

  1. Expose the port on your Tailscale network:

    Terminal window
    tailscale serve --bg 3000
  2. Start Co-Review with that host name allowed:

    Terminal window
    CO_REVIEW_ALLOWED_HOSTS=my-mac.tailnet-name.ts.net make start
  3. On the phone, open https://my-mac.tailnet-name.ts.net/m/ and choose Add to Home Screen.