# 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://getbeav.com/en/docs/agent/connect ## Before you start 1. Install the [Beav desktop app](https://getbeav.com/en/download) on the same computer. 2. The desktop installer does not add `beav` to your `PATH`, so verify `beav version` using the desktop app executable's full path; a standard macOS install uses `/Applications/Beav.app/Contents/MacOS/beav`. 3. Open Codex Desktop and send the prompt below in any task. ```text /goal Read https://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://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 the connection, identify the active workspace, read its account operating plan, style and collaboration documents, and open the knowledge library in Codex's right-hand browser panel. The installation reply includes the actual workspace, profile-read and browser results, plus the new chat link. Until the new 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 Checked 2026-10-08. This handoff uses existing Beav 2.8.14 interfaces and requires the updated website guide, or the updated Skill shipped in a new Beav build and refreshed plugin. The revised full installation and panel display still need desktop acceptance. The new task calls `creator_status`, `creator_capabilities`, and `workspace_list` to identify the active workspace. It lists knowledge read-only and uses `Read` for `profiles://creator_profile`, `profiles://soul`, and `profiles://agent`: the actual contents of `CreatorProfile.md`, `Soul.md`, and `Agent.md`. Existing positioning, audience, goals, style and collaboration preferences become reference context for continued creation. Installation verification does not rewrite profiles or generate content. The reply names the current workspace and any account explicitly identified by its profile, reports which documents were read or unavailable, and gives the [local knowledge library](https://getbeav.com/en/docs/agent/local-library) opening result. The new chat opens the URL returned by MCP in Codex's right-hand browser panel with the knowledge tab selected, so you can continue creating there. If the host has no panel tool, `library_open` opens the system browser and the Agent explains that fallback. A failed or queued panel operation is reported accurately with a link. If no workspace is active, open one in Beav first. Empty, missing or unreadable profiles are reported without claiming complete creation context. A workspace is not a social account: `accounts://current` archives require a separate actual session-account binding. The Agent must not guess the account from the space name. Relevant documents should be read again after changing spaces or losing context; profile reference material does not override your current instructions. The tool list carries everyday tools (data reads and writes, topics, image, video, voice, transcription, and delegation); for video editing, asset and manuscript management, and other work, the Agent finds tools with `creator_tools` and calls them with `creator_tool_call`. Direct calls take `{input}` and run in Beav's active workspace; use `sessionId` from `creator_session_open` to pin a workspace and a stable `idempotencyKey` for writes or generation you may retry. Codex can work directly or use `creator_delegate` when you want Beav's Agent to do the work. The browser is for you to view and pick materials; Agent data operations continue through MCP. When a task needs an API key, the Agent uses the variables you shared in Beav through `secrets_list` / `secrets_run`; see [Environment & secrets](https://getbeav.com/en/docs/agent/secrets). 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://getbeav.com/agent.md](https://getbeav.com/agent.md). ## Shared memory and creative preferences Checked 2026-10-09. Takes effect after the next Beav release and a plugin refresh; verified in source and cloud tests, not yet in Codex, Claude or WorkBuddy. Beav is your long-term creative memory. External agents read and write the same memory Beav's own Agent uses through MCP, so a preference you taught in one tool carries over to any tool that creates with Beav. You do not have to train each agent again. * Before writing, editing or generating content, the agent reads `memory://core-summary` (the core preferences, background and decisions Beav's own Agent applies every turn) and `profiles://creator_profile`, and searches `memory://` for platform or series details when needed. * When you state a preference for the future, or correct a habit you want to stay corrected, the agent saves it to Beav with `memory_manage` right away and tells you what it remembered. Changing the same preference updates it in place instead of adding duplicates; one-off requests, guesses and sensitive details are not saved. * Memories are kept per workspace and shown in Beav under Personalization → What AI knows about you. To drop one, tell the agent. When memory use is turned off in Beav, external agents get no core memories either. * What you ask for in the current conversation always overrides memory. ## Creation runs in sub-agents In Beav creation work, the external agent hands writing, generation, editing and packaging to its host's sub-agent or background task (for example a background sub-agent in Claude Code or WorkBuddy, or a sub-agent or new task in Codex where available). When the host has no sub-agents, it hands the task to Beav's own Agent with `creator_delegate`, which runs asynchronously. The main conversation does not stay "in progress", so you can keep talking, add work or adjust it at any time; when a sub-task finishes, the main agent reads back what was saved and reports. Quick questions, reading data and saving preferences stay in the main conversation. Takes effect after the next Beav release and a plugin refresh; behavior in each host is not yet verified. ## Viewing and generating images When an external agent looks at an image in Beav (assets, knowledge images, account post media, or frames from the editor), Beav returns the image itself so the agent's own model can view it. Beav no longer runs its configured vision model for this, so it uses none of that quota. The agent generates images with its own tool by default, and only uses Beav's image tool when you explicitly ask for it or when it has no image generation of its own. Video, voice and transcription still use Beav's tools. Takes effect after the next Beav release and a plugin refresh; whether each host displays returned images is not yet verified. ## Saving finished work into Beav When creation is done, the external agent saves the results into Beav. Images, videos, audio and other files it generated or exported go to Beav with `creator_file_upload` and into the asset library with `assets_import`; files made with Beav's own tools are already there and are not uploaded again. Finished writing is saved as a Beav manuscript. When it shows you a preview, the agent uses the link Beav returns (the file itself for media, the text for manuscripts) instead of a temporary local path. The library page currently only accepts connections from this computer, so phones cannot open these links yet. Takes effect after the next Beav release and a plugin refresh; behavior in each host is not yet verified. ## Save writing and build delivery packages Ask the connected AI to “save this article to my Beav manuscript library,” or specify a platform and ask it to turn a manuscript into a delivery package. The Agent saves into the active workspace and reports the title and resource references. Continue viewing or editing in Beav under **Account archives → Manuscripts**; the platform packages are attached to the same manuscript. Building a package does not publish it. This reuses existing MCP tools: discover `manuscripts_create_project`, `manuscripts_write`, and the `manuscripts_packages_begin/build/list` tools with `creator_tools`, then invoke them through `creator_tool_call`. The Agent reads the actual saved body and package resources; a chat response or arbitrary workspace Markdown file is not a manuscript-library save. Later package edits work like editing a document: the AI sends only what changes and saves, without restarting the packaging flow. Newer Beav builds write back to the same package and record the save time, with no version bump and no new package; the package ID and URI stay the same. Saving an article alone does not require selecting a platform. On 2026-10-08, real MCP calls against Beav 2.8.14 verified creation, body save/read-back, manuscript listing, generic text package build/read-back, same-package update, and moving the test manuscript to recoverable trash. This check did not cover image packages, paid media generation or platform publication. The interfaces already exist; the expanded Skill guidance requires a new Beav build and plugin refresh. Installation verification only reads data and discovers capabilities, without creating test manuscripts. ## Sharing environment variables and secrets Verified against source on 2026-10-08. Requires a new Beav build containing PR #39 and refreshed Beav Creator plugin guidance; the WorkBuddy connector documentation is version 1.0.4. Older installations may not include these features. Real desktop use and each external host's approval and sandbox behavior remain unverified. Open **Environment & secrets** from Beav's lower-left account menu to edit, reveal, copy, enable or disable variables. The **.env editor** supports bulk edits: Secret values stay in the system keychain, `••••••••` preserves an existing value, and adjacent comments become notes. Removing a line deletes that variable after confirmation. Importing .env only merges entries and does not remove existing variables. New variables are not shared. Choose **Inject only** per variable to let an external Agent discover names and notes with `secrets_list` and inject values into local commands with `secrets_run`. **Read** also permits `secrets_read` to return plaintext. An authorized client credential is required. If a variable is unavailable, enable or share it in Beav instead of pasting its value into chat. Command results redact literal values, including short values and fragments at the output limit. Inject only does not hide plaintext from the authorized client: clients and commands can still read or forward injected values, so share only with trusted tools. Commands run in the MCP process launched by the external host; approval and sandboxing depend on that host's configuration. The default timeout is 120 seconds, the maximum is 600 seconds, and each output stream is limited to 64KB. ## Connecting WorkBuddy Send this prompt to WorkBuddy: ```text Read https://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://getbeav.com/en/download), waits, then continues in the same task; it does not prepare or install the plugin yet. `codebuddy` does not need to be on the shell `PATH`. 3. Gives you the full path to the installed Beav desktop app's executable (shown below as ``). In a normal Terminal outside WorkBuddy, run `"" open --output json` followed by `"" extension prepare workbuddy --output json`, then send WorkBuddy only the second command's `marketplacePath`. 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://getbeav.com/workbuddy.md](https://getbeav.com/workbuddy.md).