# Connect Codex Desktop and WorkBuddy

> Install the Beav Creator Plugin from one line on this site, then verify the connection between Codex or WorkBuddy and Beav MCP on your machine.

- Source: https://www.getbeav.com/en/docs/agent/connect

## Before you start

1. Install the Beav desktop app on the same computer. It includes the required commands, so a separate CLI installation is unnecessary; an existing standalone CLI also works.
2. Verify `beav version` using the installed executable's full path; with a test archive you can use its `bin/beav` path instead.
3. Open Codex Desktop and send the prompt below in any task.

```text
/goal Read https://www.getbeav.com/agent to install the Beav Creator plugin and set up a new task for me.
```

## What Codex does

1. Reads the machine install guide served at `/agent`.
2. Locates the CLI bundled inside Codex Desktop without depending on your terminal `PATH`. In the current macOS ChatGPT app, it lives at `Contents/Resources/codex-cli/CodexCLI.app/Contents/MacOS/codex`; verify the actual bundle with `plugin --help`.
3. Checks for Beav first. If it is missing, Codex asks you to [install the desktop app](https://www.getbeav.com/en/download), then continues in the same task without attempting plugin installation yet.
4. Runs `beav extension prepare codex --output json`. If Codex's command sandbox blocks local runtime or file access, it asks you to run `beav open --output json` and then the preparation command in a normal Terminal outside Codex. Send back only the returned `marketplacePath`, never the full JSON or credentials.
5. Checks the local marketplace and plugin manifests, adds or updates `beav-local` with Codex CLI, then runs `plugin add beav-creator@beav-local --json` to refresh an existing cache as well as install a new plugin.
6. Reads `plugin list --json --marketplace beav-local` and the installed cache to confirm the plugin is enabled and its version, MCP command, and skill match the prepared package.
7. Creates a new task to verify `creator_status`, `creator_capabilities`, `workspace_list`, and read-only data access when a workspace is active. Until that task verifies the connection, it reports installation complete but connection verification pending.

`beav extension install codex --output json` is a compatibility alias that also only prepares the plugin: it never calls a bare `codex` command or edits your Codex configuration.

## How the new task collaborates

The new task calls `creator_status`, `creator_capabilities`, and `workspace_list` first, then discovers the direct tools. With an active workspace, it opens `creator_session_open` and checks read-only knowledge access. Codex can use Beav's data and business tools directly, or call `creator_delegate` when you want Beav's internal Agent to do the work. When you need to review, approve, or fine-tune something, Beav returns a localhost browser handoff; the browser is your workspace, not the Agent control plane.

For delegated work, follow-up changes keep querying and continuing the same Beav task. A delegated task's terminal state does not prove content was saved; read the actual resource reference when the request requires a saved artifact. Direct tool calls do not require a delegated task.

The machine-readable install contract lives at [https://www.getbeav.com/agent.md](https://www.getbeav.com/agent.md).

## Connecting WorkBuddy

Send this prompt to WorkBuddy:

```text
Read https://www.getbeav.com/workbuddy to install the Beav Creator plugin and connect it to my local Beav workspace.
```

WorkBuddy then:

1. Reads the machine install guide served at `/workbuddy`.
2. Locates the CodeBuddy CLI bundled inside the WorkBuddy app and checks for a local Beav installation. If Beav is missing, WorkBuddy asks you to [install the Beav desktop app](https://www.getbeav.com/en/download), waits, then continues in the same task; it does not prepare or install the plugin yet. Neither `codebuddy` on the shell `PATH` nor a separate Beav CLI is required.
3. Gives you the exact path to the installed Beav executable. In a normal Terminal outside WorkBuddy, run `"<BEAV_CLI>" open --output json` followed by `"<BEAV_CLI>" extension prepare workbuddy --output json`, then send WorkBuddy only the second command's `marketplacePath`. The desktop app includes these commands; a separate Beav CLI is not required. WorkBuddy's command sandbox may block Beav from writing local runtime files, so do not keep retrying preparation there.
4. Reads the plugin manifests at that path, validates the marketplace with `codebuddy plugin validate`, then installs `beav-creator@beav-local` at user scope. Do not send the full preparation result or credentials.
5. Hot-reloads the plugin through `/reload-plugins` and verifies the same Beav MCP with `creator_status` and `workspace_list`.

`beav extension install workbuddy --output json` is a prepare-only compatibility alias. Codex and WorkBuddy differ only in host install format and load mechanism; both share the same Beav Creator Skill, Creator Gateway, internal Agent, and localhost user workspace.

The machine-readable install contract lives at [https://www.getbeav.com/workbuddy.md](https://www.getbeav.com/workbuddy.md).