# 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 and verify it. If Beav is missing, ask the user to install it before continuing. If Codex cannot prepare Beav because its command sandbox blocks local runtime or file access, ask for the narrow Terminal recovery in section 4, then continue this same task. Do not claim success from preparation or installation alone. 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. 5. The new task verifies MCP connectivity and discovery as described below. Until that read-back returns, report "installed; connection verification pending", not "ready to use". 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-cli/CodexCLI.app/Contents/MacOS/codex` - The equivalent `Contents/Resources/codex-cli/CodexCLI.app/Contents/MacOS/codex` inside an installed Codex app bundle. - Older bundles may place `codex` directly under `Contents/Resources/`; use that path only if the file exists and passes the check below. On other platforms, inspect the installed desktop application's resources. Verify the candidate with: `"" 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. On macOS, the installed desktop executable: `/Applications/Beav.app/Contents/MacOS/beav`. 2. `command -v beav` or the platform equivalent. 3. macOS/Linux compatibility path: `~/.local/bin/beav`. 4. A path supplied by the user for an unpacked test bundle, such as `/bin/beav`. Verify it with `"" version` and `"" --help`; require the `extension prepare` command. The Beav desktop app executable includes these CLI commands; a separate Beav CLI installation is not required. If no usable Beav executable is installed, tell the user directly: "Please install the Beav desktop app first: https://www.getbeav.com/download. Then reply here so I can continue the plugin installation." Pause before preparing or installing the plugin, then resume this same task after Beav is installed. If Beav is installed but lacks `extension prepare`, ask the user to update Beav. Do not run a remote installer. ## 4. Prepare the local plugin Run: `"" extension prepare codex --output json` Read the returned `marketplacePath`, `pluginId`, `pluginVersion` and `verificationTools`. Require `host` to be `codex` and `pluginId` to be `beav-creator@beav-local`. If preparation fails because Codex cannot write Beav's local data or start its runtime, do not keep retrying inside the same sandbox. Give the user these commands with the verified executable path, to run in a normal Terminal outside Codex: `"" open --output json` `"" extension prepare codex --output json` Ask the user to reply with only the second command's `marketplacePath`, never the full JSON or a credential. Continue this task after the reply. Inspect `/.agents/plugins/marketplace.json`, `/plugins/beav-creator/.codex-plugin/plugin.json` and `.mcp.json`; require marketplace `beav-local`, plugin `beav-creator`, a matching version, and an installed Beav executable in the MCP command. Do not invent paths, read the credential file, or edit Codex configuration files directly. Preparation is not installation. It creates a host-specific client grant and a private credential file; the plugin contains only that file's path. Do not read, print, copy or send its token. Repeated preparation preserves the grant. Use `--reauthorize` only after explicit user authorization to replace a revoked grant; ordinary tool calls cannot undo revocation. This direct-tool contract requires the updated Beav runtime and plugin 0.2.0 or newer. If these fields or tools are absent, report that Beav needs updating rather than claiming the new capabilities work. The compatibility command `extension install codex --output json` has the same prepare-only behavior. ## 5. Install idempotently through Codex First inspect current state: `"" plugin marketplace list --json` `"" plugin list --json --marketplace beav-local` - If marketplace `beav-local` is absent, run `"" plugin marketplace add "" --json`. - If `beav-local` exists but points to a different path, remove only that marketplace with `plugin marketplace remove beav-local` and add the prepared path again. - Run `"" plugin add beav-creator@beav-local --json` for both first installs and updates. This refreshes this plugin's local cache, including when its ID already exists. Record the returned `installedPath`. Never remove or modify unrelated marketplaces or plugins. ## 6. Verify installation Run `"" plugin list --json --marketplace beav-local` again and require an `installed` entry whose `pluginId` is `beav-creator@beav-local`, `installed` and `enabled` are true, and `version` matches the prepared manifest. Confirm its `marketplaceSource.source` resolves to `marketplacePath`. Read the plugin at `installedPath`: its manifest version and `.mcp.json` command must match the prepared plugin, and `skills/beav-creator/SKILL.md` must exist. Do not read the credential file. 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, creator_capabilities and workspace_list. Confirm the direct tool catalog is available. When an active workspace exists, open a stable creator_session_open context and perform a read-only List of knowledge://; accept an empty result. Then continue my stated request or ask what I want to do. 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. If task coordination is available, wait for the new task's MCP read-back and report its result. If the new task cannot discover the plugin or cannot connect, report the exact failure and ask the user to restart Codex Desktop and retry in a new task if needed. Until a new task verifies the tools, report "installed; connection verification pending". 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`, `creator_capabilities` and `workspace_list`. - Discover the full paginated MCP catalog or use the host's tool search. Call `creator_session_open`, then use the same native Beav data and business tools with `{sessionId,idempotencyKey,input}`. Use a stable key for each logical call and reuse it after uncertain transport failures. Direct calls require the session workspace to be active in Beav. - Use direct tools for knowledge, assets, manuscripts, profiles, history and media work. Use `creator_delegate` only when the user wants Beav's Agent to perform the work; it is optional, not a requirement for data access. - For delegated Beav tasks, 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. - Inspect returned results and read actual saved resource refs when the request requires persisted content. An ordinary answer need not create an artifact; task completion alone is not evidence that saved content was read back. ## Human documentation - Installation page: https://www.getbeav.com/agent - Beav download: https://www.getbeav.com/download - Agent guide: https://www.getbeav.com/docs/agent - Connection details: https://www.getbeav.com/docs/agent/connect