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

# Obversa in cmux

> One Command Palette entry and five scripts: the right editor on the right worktrees, and local pages in splits beside the terminal.

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:

```json ~/.config/cmux/cmux.json theme={null}
{
  "schemaVersion": 1,
  "commands": [
    {
      "name": "Order Workspace",
      "keywords": ["obversa", "order", "workspace"],
      "command": "/Users/you/.obversa/cmux/bin/obversa-order-workspace"
    }
  ]
}
```

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:

```bash Terminal theme={null}
curl -fsSL https://obversa.ai/install/cmux.sh | bash
```

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:

```bash Terminal theme={null}
obversa-order-workspace --shared ~/code/obversa-shared
```

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:

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

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

```bash Terminal theme={null}
obversa-surface http://localhost:4400/review --direction right
```

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

* [Review a diff in a host pane](/docs/hosts/review): the review page that opens
  in a split.
* [Surfaces](/docs/concepts/surfaces): the page a question opens on, and why it
  ends once.
* [Watch a run in the browser](/docs/driving/monitor): the run's own page, which
  the glue can place the same way.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.