Skip to main content
Open the two worktrees an order works on in one editor window, and have every question a run asks open in a browser split beside the terminal that started it. Use it when you drive runs from cmux. Outside cmux the same scripts fall back to your default browser, so nothing here is required to run Obversa. Obversa is a guest in whichever host you use, and cmux is the first: the glue is setup rather than a product, with no host fork and no new UI. The whole configuration is one Command Palette entry, written to ~/.config/cmux/cmux.json by the installer when you have no cmux configuration yet:
~/.config/cmux/cmux.json
The entry names the launcher by absolute path, because cmux runs it from whatever directory the workspace is in. When you already have a configuration, the installer copies it aside and prints the entry for you to add. Set-up needs:
  • macOS, because the default-browser fallback uses open.
  • The five scripts in ~/.obversa/cmux/bin, on your PATH.
  • The Shared root, once: export OBVERSA_SHARED_ROOT=<shared worktree>.

​
Install

Install the glue with one command. It’s five small scripts and one palette entry, not an npm package:
Terminal
The installer puts the scripts in ~/.obversa/cmux/bin and never edits a configuration you already have. To do it by hand, the scripts are in hosts/cmux/bin in the repository, and the palette entry above names the launcher by absolute path. Prefer to have an agent do it? Paste this:
Install the Obversa cmux glue. Fetch the five scripts from hosts/cmux/bin in github.com/jonny981/obversa into ~/.obversa/cmux/bin, make them executable, add a Command Palette entry named “Order Workspace” to ~/.config/cmux/cmux.json pointing at the absolute path of obversa-order-workspace, and add ~/.obversa/cmux/bin to my PATH. Do not put OBVERSA_SURFACE_BIN or PLANNOTATOR_BROWSER in any profile or settings file: those bind per workspace, and a global one sends every review to the wrong host.

​
Open an order workspace

Run Order Workspace from the Command Palette. The first run shows the cmux trust prompt. A project-local .cmux/cmux.json overrides the global entry, so a repository can carry its own and the pair never conflicts. From a terminal:
Terminal
Each order binds two worktrees. The Project worktree holds your product source. The Shared worktree holds the Context and Workflow that all projects share. Neither root appears inside the other. The generator writes one editor workspace file with both roots to ~/.local/state/obversa/workspaces/, outside both trees, and opens it with code (override with $OBVERSA_EDITOR_CMD). It refuses nested or identical roots.

​
Create a workspace

Create workspaces through the host’s launcher, so every terminal and agent in the workspace has the two placement variables bound to the glue’s own scripts:
Terminal
OBVERSA_SURFACE_BIN places Obversa surfaces and PLANNOTATOR_BROWSER places the Plannotator review page. The binding is per launch host, never global: don’t put either variable in a shell profile or an agent client’s settings, and remove an old global PLANNOTATOR_BROWSER from ~/.claude/settings.json if one is there. A global binding sends every launch to one host, so a review started elsewhere would land here. In a workspace opened without the launcher, export OBVERSA_SURFACE_BIN as the absolute path of obversa-surface in that workspace. Apply configuration changes with cmux reload-config.

​
Place a page

A surface is a small page for one decision. In cmux it opens as a browser pane split beside the terminal; outside cmux the same command opens your default browser, so every script stays usable in a plain terminal:
Terminal
Callback gate surfaces open the same way when a router launches them, and the Plannotator review page opens in a split through PLANNOTATOR_BROWSER. Only that page routes into cmux; no other tool reads the variable, so no other link changes behaviour. The URL a surface hands the glue is a one-time launch URL that opens the session: single use, valid for a minute, and the page URL with its token never goes into a process argument. That launch URL still opens the review, so every command the glue uses runs by absolute path from a fixed list of system directories (/usr/bin, /bin, /usr/local/bin, /opt/homebrew/bin), never by a bare name looked up on PATH. A host may name other directories in OBVERSA_SYSTEM_BIN_DIRS, colon-separated. On Linux the glue doesn’t run xdg-open, because xdg-open runs its own helpers by bare name; the URL is printed on stderr for you to open, as it is on any platform with no opener found.

​
Failure

Every failure path lands somewhere safe. When cmux is absent, wedged, or returns an unusable topology, the URL opens in the default browser. When the Shared root is missing, the generator stops with the exact flag to pass. A cancel during the lookup opens nothing. Wrong placement is treated as worse than a plain browser, so the scripts never guess a workspace.

​
Limits

  • One palette entry, five scripts, nothing else. cmux supplies the panes, the layout and the keybindings; Obversa supplies the workspace file and the surface placement. Remove the glue and cmux is exactly as it was.
  • macOS only for the installer and the browser fallback.

​
Next steps