This page covers connecting Codex to Loom: what loom setup does for it, the equivalent manual commands, how to trust the hooks, and how to update or remove it.
Run loom setup and leave codex selected (add --base <your server> for a private server). Setup first signs you in (your email address, consent and a sign-in code), unless ~/.loom/stores.toml already holds your credentials for the server: then it prints Using your existing Loom stores for <server>; run loom login to sign in again. and skips the sign-in. For Codex it then runs the two commands below, and checks codex plugin list --json for exactly one enabled loom@loom entry.
Setup installs the plugin from the marketplace of the server it signed in to: <server>/loom-plugins.git. The server is --base, or the single origin recorded in ~/.loom/stores.toml, or LOOM_WEB_BASE, or https://loomcloud.ai (see Choosing the server). For a hosted account that is https://loomcloud.ai/loom-plugins.git.
Setup still writes your stores in both cases below, then exits with status 3 and marks the run partial.
A private server reached over http:// does not serve a plugin marketplace, so setup skips the Codex install. It prints this line once:
Plugins need an https server: the Loom plugin marketplace is not served over http, so the claude/codex plugin install was skipped. Your store is set up.and this row, with no restart line:
codex skipped (plugins need an https server)With --json the line goes to stderr and the result for codex has "action": "skipped" and "error": "codex: plugins need an https server; skipped". Move the server to https, or install the plugin from a marketplace you can reach as in Manual install.
If a loom marketplace is already installed from a different origin, setup never updates or replaces it. The row reads:
codex FAILED -- codex: the existing Loom marketplace comes from <listed source> but this setup is for <base> (<base>/loom-plugins.git), so nothing was changed. To switch deliberately, run `codex plugin remove loom@loom`, then `codex plugin marketplace remove loom`, then re-add it with `loom setup --base <base>`.<listed source> is shown without credentials, query or fragment. For https://loomcloud.ai the last command reads loom setup. To switch on purpose, run the commands in the row:
codex plugin remove loom@loom
codex plugin marketplace remove loom
loom setup --base https://<your-server>If Codex does not report where the installed marketplace came from and the server is not https://loomcloud.ai, setup updates it anyway and prints under the row: codex: the existing Loom marketplace's origin is not exposed by this harness, so it was updated without checking it came from <base>.
Codex 0.159.3 reports the installed marketplace's source in codex plugin list --json (marketplaceSource.source).
Use the exact codex executable you use for normal sessions or a fixed-session worker.
codex plugin marketplace add https://loomcloud.ai/loom-plugins.git
codex plugin add loom@loomThe supported plugin identity is loom@loom, from the marketplace named loom.
The plugin starts its MCP server with the bare command uv. When the CLI installer (which loom setup relies on) finds no uv, it installs a copy at ~/.loom/bin/uv. From v0.672 the installer also puts ~/.loom/bin on your PATH for new terminals (see Install the CLI); with an earlier installer, make sure uv is on the PATH of the shell that starts Codex (for example export PATH="$HOME/.loom/bin:$PATH"). The hooks use ~/.loom/venv when it is ready and fall back to uv otherwise.
Manual install only connects the plugin. Run loom login (or loom setup) first so ~/.loom/stores.toml exists.
If git does not trust the server's self-signed certificate,
marketplace addfails withgit clone ... failed with status exit status: 128 ... server certificate verification failed. Add the server's certificate to the operating system trust store (or use a certificate from a public or company CA); see Trust the server's certificate.
~/.loom/stores.toml. Re-trust the workspace if Codex prompts for it.Run the bundled skill:
$loom:loom-installNot tested end to end: the output and behavior of $loom:loom-install. It verifies the runtime, MCP startup, skills, hooks and every configured store without printing credentials, and refreshes the shared loom CLI runtime if needed.
loom@loom and choose the persistent Trust/Enable action.Trust and enable all six Loom hook events: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact and PostCompact. In the Codex desktop app you can review them under Settings → Hooks.
Not tested in a live Codex session: the hook trust prompt, the Settings → Hooks screen, and whether a restart or new task is needed.
A successful loom setup --harness codex --base https://<your-server> run (tested against a private server) ends with the stores line (Loom store(s) ... configured in ~/.loom/stores.toml., or the Using your existing Loom stores line when the sign-in was skipped) and:
codex installed and verified
Codex: restart the CLI (or run `codex` again) so it re-reads ~/.loom/stores.toml, then re-trust this workspace if Codex prompts for it.Afterwards codex plugin list --json shows loom@loom installed and enabled.
From v0.672, loom setup also runs codex mcp list --json and does not call Codex verified unless it shows an enabled loom entry whose command (uv) is found on PATH. Otherwise the row reads codex FAILED -- codex: the Loom plugin is installed but its MCP server is not running (<reason>), so its tools will not be available. Fix that, then re-run setup. (v0.674 and later add, on Linux and macOS, If this terminal predates the Loom installer, run . "$HOME/.loom/env" first.), where <reason> is, for example, `its command 'uv' was not found on PATH. Codex lists configuration, not connection state, so this check cannot detect a server that is found but then crashes. The restart line is still printed under a FAILED row, and loom setup exits with status 3. codex mcp list --json returns the entry with name, enabled and transport.command (uv`), as confirmed on Codex 0.159.3.
Not tested in a signed-in Codex session: the result of this prompt, and whether MCP calls work while hooks are untrusted.
Ask your agent:
List my Loom stores and describe which store is the default.codex plugin marketplace upgrade loom
codex plugin add loom@loomRestart Codex and rerun $loom:loom-install. loom setup also performs the update when you re-run it.
codex plugin remove loom@loom
codex plugin marketplace remove loomThe second command is optional. It also deletes the local marketplace snapshot and the [marketplaces.loom] entry in ~/.codex/config.toml; after plugin remove alone that entry stays. Removing the plugin does not delete your account, your stores or ~/.loom/stores.toml.