# Install Beav Creator in Codex Desktop

Beav is a local-first creator workspace. This guide is for a Codex Agent running on the same computer as the user's Beav installation. The Beav browser UI is for the user; use the Beav Creator MCP tools for machine-to-machine work. Do not automate the browser.

## Completion contract

Complete the installation yourself. Do not stop after explaining commands or ask the user to copy commands into a terminal.

You are complete only when:

1. Beav has prepared the local plugin marketplace.
2. The Beav Creator plugin is installed and enabled in Codex.
3. You have verified the installed plugin entry.
4. You have created a new Codex task for the user, because the current task may not hot-load a newly installed MCP server.

If a concrete blocker remains, report the exact failed step and the single user action needed to continue.

## 1. Confirm the local environment

- Continue only when this Agent can access the user's local filesystem and processes on the computer where Beav is installed.
- If this is a hosted chat, remote container, or another computer, tell the user to paste their original request into Codex Desktop on the Beav computer.
- Do not expose Beav to the public internet and do not use browser automation as a fallback.

## 2. Locate the Codex Desktop bundled CLI

Use the CLI bundled with the running Codex or ChatGPT Desktop application. Do not assume a bare `codex` command exists on the user's shell `PATH`.

On macOS, inspect installed application bundles, including:

- `/Applications/ChatGPT.app/Contents/Resources/codex`
- `/Applications/Codex.app/Contents/Resources/codex`

On other platforms, inspect the installed desktop application's resources. Verify the candidate with:

`"<CODEX_CLI>" plugin --help`

Do not download a different Codex binary when the desktop-bundled CLI is available.

## 3. Locate Beav

Find the installed Beav CLI in this order:

1. `command -v beav` or the platform equivalent.
2. macOS/Linux compatibility path: `~/.local/bin/beav`.
3. A path supplied by the user for an unpacked test bundle, such as `<bundle>/bin/beav`.

Verify it with `"<BEAV_CLI>" version`. If Beav is not installed, direct the user to https://beav.ziz.hk/docs/getting-started/cli and stop without running an unapproved remote installer.

## 4. Prepare the local plugin

Run:

`"<BEAV_CLI>" extension prepare codex --output json`

Read the returned `marketplacePath` and `pluginId`. The expected plugin ID is `beav-creator@beav-local`. Do not invent paths and do not edit Codex configuration files directly.

The compatibility command `extension install codex --output json` has the same prepare-only behavior.

## 5. Install idempotently through Codex

First inspect current state:

`"<CODEX_CLI>" plugin marketplace list --json`

`"<CODEX_CLI>" plugin list --json`

- If marketplace `beav-local` is absent, run `"<CODEX_CLI>" plugin marketplace add "<marketplacePath>" --json`.
- If `beav-local` exists but points to a different path, remove only that marketplace and add the returned `marketplacePath` again.
- If plugin `beav-creator@beav-local` is absent, run `"<CODEX_CLI>" plugin add beav-creator@beav-local --json`.
- If the plugin is already installed and enabled from the returned local marketplace, do not reinstall it.

Never remove or modify unrelated marketplaces or plugins.

## 6. Verify installation

Run `"<CODEX_CLI>" plugin list --json` again and require an installed, enabled entry whose `pluginId` is `beav-creator@beav-local`. Confirm that its marketplace source is the Beav local marketplace returned above.

Do not claim success from a command exit code alone; verify the read-back entry.

## 7. Create the new task

Use the Codex task/thread creation capability to create a new user-visible task with this objective:

`Use the Beav Creator plugin to connect to my local Beav workspace. Check creator_status and workspace_list, then ask what I want to create. Use MCP for all machine operations and open the localhost UI only when I need to view, approve, or edit something.`

After creating it, give the user the new task link or open it in Codex Desktop. Do not attempt to simulate a fresh task inside the current conversation.

## New-task operating rules

The Beav Creator Skill in the installed plugin is the source of truth. At minimum:

- Start with `creator_status` and `workspace_list`.
- Delegate creator work through typed MCP tools; Beav's internal Agent owns planning and execution.
- Poll the same task, preserve revisions, and answer input requests through typed continuation.
- Treat the localhost browser UI as a human workbench, never as the Agent control plane.
- Claim completion only after a terminal task result and readable required artifacts.

## Human documentation

- Installation page: https://beav.ziz.hk/agent
- Beav download: https://beav.ziz.hk/download
- Agent guide: https://beav.ziz.hk/docs/agent
- Connection details: https://beav.ziz.hk/docs/agent/connect