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.
Domain skills
Section titled “Domain skills”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.
Requirements
Section titled “Requirements”- 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.
Install
Section titled “Install”Add this repository as a Codex marketplace, then install the rel plugin:
codex plugin marketplace add https://github.com/rel-me/rel-tools.git --ref maincodex plugin add rel@relStart a new Codex task after installation so the task loads the plugin’s skill and MCP tools.
What the plugin adds
Section titled “What the plugin adds”The plugin contains:
- the bundled REL MCP server configuration, with automatic app discovery;
- the
rel-browserskill for safe session selection and browser workflows; - the
crawl-websites-with-relskill 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, andclick-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.
Verify
Section titled “Verify”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.
Diagnose navigation
Section titled “Diagnose navigation”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.
Update
Section titled “Update”Refresh the marketplace snapshot and reinstall the current plugin version:
codex plugin marketplace upgrade relcodex plugin add rel@relStart 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.