> ## Documentation Index
> Fetch the complete documentation index at: https://docs.obversa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Obversa in cmux

> Host glue for cmux: the correct editor opens on the correct worktrees, and local web surfaces open in splits beside the terminal.

Obversa is a guest in the host that you selected. cmux is the first host.
The glue for cmux is setup, not a product: configuration plus small
scripts. There is no host fork and no new UI.

## What you get

* One command in a workspace opens one editor window with the two Order
  roots: the Project worktree and the Shared worktree, as peers.
* A local web surface opens in a browser split beside the terminal.
* The Plannotator review page opens in a split. Every other link keeps
  your default browser.
* Callback Gate surfaces use the same door when a router launches them.

## The two-root workspace

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 glue generates one editor workspace file with both roots and opens
it. The file lives outside both trees, so no worktree carries host
state. Your editor stays your editor.

## Surfaces in splits

A surface is a small user interface for one decision. In cmux, a surface
opens as a browser pane in your workspace, split beside the terminal.
Outside cmux, the same command opens your default browser. The fallback
keeps every script usable in a plain terminal.

The URL a surface hands the glue is a one-time launch URL that opens the
session (single use, valid for a minute; the page URL with its token is
never placed in a process argument), and it is still the one door to the
review, so every
command the glue runs (`cmux`, macOS's `open`, the `python3` that reads
the cmux tree, and the few coreutils the cmux route needs) 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 does not
run `xdg-open`, which 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, and nothing else receives it.

## One route for Plannotator

Plannotator opens its review page through one environment variable,
`PLANNOTATOR_BROWSER`, and the workspace launcher below binds it to the
glue script for the workspaces it creates. Only the review page routes
into a cmux split; no other tool reads the variable, so no other link
changes behavior.

## Set up

The glue is a handful of scripts in `hosts/cmux/bin/` plus one Command
Palette entry. It targets macOS today: the default-browser fallback uses
`open`.

Put the scripts on your PATH first, or call them by full path:

```sh theme={null}
export PATH="$PATH:<checkout>/hosts/cmux/bin"
```

1. Obversa checkouts carry the palette entry in `.cmux/cmux.json`. Open a
   cmux workspace on the repository and run **Order Workspace** from the
   Command Palette. The first run shows the cmux trust prompt.
2. For every other workspace, add the same entry to
   `~/.config/cmux/cmux.json` with the script's absolute path. The
   project-local entry overrides the global one, so the pair never
   conflicts.
3. Set the Shared root once: `export OBVERSA_SHARED_ROOT=<shared worktree>`.
4. Create workspaces through the host's launcher, which binds both
   placement variables — `OBVERSA_SURFACE_BIN` for Obversa surfaces and
   `PLANNOTATOR_BROWSER` for Plannotator — to this checkout's scripts for
   every terminal and agent in the workspace:

   ```sh theme={null}
   obversa-cmux-workspace <repository-directory>
   ```

   The binding is per launch host, never global: do not put either
   variable in a shell profile or an agent client's settings, and remove
   an old global `PLANNOTATOR_BROWSER` entry from `~/.claude/settings.json`
   if one is there — a global binding sends every launch to one host, so a
   review started in another host would land in this one instead of where
   it started. In a workspace opened without the launcher, export
   `OBVERSA_SURFACE_BIN` as the absolute path of `obversa-surface` in that
   workspace; outside cmux, surfaces open in the default browser.
5. Apply with `cmux reload-config`.

## Use

```sh theme={null}
# Open the two-root editor workspace for the current repository.
obversa-order-workspace --shared ~/code/obversa-shared

# Open a local webapp in a browser split beside this terminal.
obversa-surface http://localhost:4400/review --direction right
```

The generator writes the workspace file to
`~/.local/state/obversa/workspaces/` and opens it with `code` (override
with `$OBVERSA_EDITOR_CMD`). It refuses nested or identical roots.

## When something fails

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.

## Your host stays yours

The glue adds one Command Palette entry, three scripts, and 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.