Skip to content

Codex plugin

The REL plugin connects Codex to REL’s persistent embedded Chromium sessions. It configures the MCP server bundled with the installed app and adds the rel-browser skill for interactive browser work plus the crawl-websites-with-rel skill for restartable, history-preserving crawls.

Related documents: MCP server, browser diagnostics, session scope and CLI.

For provider setup and per-Session assignment, see Configure proxies.

The plugin bundles a site-specific skills collection in plugins/rel/skills/:

Skill Domain Guidance
rel-reddit reddit.com Login, private cookie export, fresh-cookie Session creation, bounded 429 recovery, and configured rotating routes
rel-zillow zillow.com Profile settings, geographic filters, maps, and property details
rel-craigslist craigslist.org Regional searches, category scope, postings, and expiry
rel-google google.com Search Native identity, direct routing, query scope, and source verification
rel-x x.com, twitter.com Login snapshots, search tabs, timelines, and thread coverage
rel-duckduckgo duckduckgo.com Regional search, result expansion, and source links
rel-loopnet loopnet.com Commercial-property filters, units, and gated details

These skills load for their own domains and are available to both plugin hosts. Their setup guidance comes from local REL.app Profiles inspected on 2026-10-27; the plugin does not install those Profiles or ship proxy aliases, credentials, or cookie files. Discover current Profiles before creating a Session. RYM, AOTY, Metacritic, and Discogs are excluded from this collection.

Reddit’s fresh-cookie and rotating-route workflow is specific to Reddit. It honors rate-limit waits and bounds replacement attempts; it cannot guarantee access. Cookie-file selection is currently an app workflow, not a CLI/MCP creation option, and REL has no public Session reset API. See cookie files and Session scope.

  • macOS 15 or later;
  • REL 0.1.156 or later installed on the Mac, with the Project/Session MCP adapter;
  • a Codex release with plugin marketplace support.

The launcher requires adapter version 0.1.156 or later and the rel-project-sessions-v1 API contract. An unsupported adapter stops with an update instruction before exposing tools. Operational calls reject older local runtimes as well. Restart the MCP connection after updating the plugin or app.

REL.app must be installed so Codex can start its bundled Contents/Resources/rel-mcp adapter. The app does not need to be running for plugin discovery or rel_status; other validated tool calls start it lazily.

The plugin checks /Applications/REL.app, ~/Applications/REL.app, then macOS application registration using bundle ID me.rel.Rel. Set REL_APP_PATH in the MCP host’s environment to select a custom bundle path. Discovery does not launch REL; an invalid override reports an error without falling back.

Add this repository as a Codex marketplace, then install the rel plugin:

Terminal window
codex plugin marketplace add https://github.com/rel-me/rel-tools.git --ref main
codex plugin add rel@rel

Start a new Codex task after installation so the task loads the plugin’s skill and MCP tools.

The plugin contains:

  • the bundled REL MCP server configuration, with automatic app discovery;
  • the rel-browser skill for safe session selection and browser workflows;
  • the crawl-websites-with-rel skill for rendered-link discovery, readiness, checkpoints, capture metadata, bounded retries, and session recovery;
  • the app-bundled MCP tools, including bounded semantic reading, opt-in untrusted website notifications, observations, session traces, non-blocking debug state, optional diagnostic bundles, and inline or file-backed screenshots;
  • all eight canonical page actions: click, wait-for, type, clear, press, select, wait, and click-link.

The plugin does not add another browser backend. REL.app remains the only Chromium owner, and every tool call flows through the local versioned API. See the MCP tool reference for complete inputs and action semantics.

Begin with a read-only check in a new task:

Use the REL MCP server. Call rel_status, then rel_list_sessions. Do not navigate anywhere.

Codex should discover the rel_* tools supplied by the installed app without opening REL. If REL is already running, rel_status reports the app, local agent, Browser Proxy, and embedded Chromium bridge. Otherwise it returns the local connection error without launching the app; rel_list_sessions then starts REL lazily.

While a selected Session is waiting or after it fails, use rel_debug_state and rel_session_trace with its exact ID. Preserve the original error details and snapshot age before retrying or replacing the Session. Use rel_debug_bundle for a bounded shareable artifact; HTML and screenshots default to off.

Select a Project with rel_list_projects, then inspect its Sessions with rel_list_sessions({"project_id":"ProjectDefault"}). To create independent browser state, use rel_create_session with project_id and optional profile; reuse the returned session_id. A Profile name never identifies a live login. Use rel_close_session for one exact Session when the workflow owns cleanup.

Refresh the marketplace snapshot and reinstall the current plugin version:

Terminal window
codex plugin marketplace upgrade rel
codex plugin add rel@rel

Start another new task after updating so it uses the refreshed plugin cache.

The Codex and Claude Code packages share a plugin version, independent of the REL app version. Regular app promotion checks the plugin directory and both marketplace manifests. When their contents have changed since the last plugin version bump, promotion tests the launcher and publishes a synchronized patch bump on this repository’s main. Unchanged plugin contents keep their version; app-bundled MCP updates alone do not require a plugin release. Staging and Beta releases do not update the shared marketplaces.

Marketplace publication does not refresh an already installed plugin cache. Use the update commands above and restart or reload the client as directed.