Docs / How-to guides
Connect Codex
Add the Reliquary plugin to Codex once per computer, then sign in from Codex; no token to copy.
Reliquary accepts Codex's sign-in (Codex's own client, coming back to your computer on any port). The steps below follow Codex's documentation; they have not yet been walked through end to end in Codex itself, so if a step looks different, send feedback.
With the plugin
The Reliquary plugin adds the connection and teaches Codex how to work in a vault.
-
In a terminal, add the Reliquary marketplace:
codex plugin marketplace add andersthemagi/reliquary -
Start Codex, run
/plugins, choose Reliquary and install it. Then start a new session. -
Sign in. Codex may offer to sign you in as it installs the plugin; if it doesn't, run
codex mcp login reliquaryin a terminal. Your browser opens Reliquary. Sign in if you need to, then choose:- All my vaults, including ones I join later, or Only the vaults I tick (if you belong to more than one vault, nothing is chosen for you: see Keep client work separate);
- Read only (read, search and follow changes) or Read and write (also write open files and propose changes).
-
Choose Allow. Back in Codex,
/mcpshows reliquary as connected. -
Run
/hooksand trust the Reliquary hooks. Codex skips a plugin's hooks until you do, and asks again when an update changes them.
The plugin carries no token: signing in is still yours to do. Codex keeps the connection and refreshes it by itself.
It also adds:
- A skill for working in a vault: when to write and when to propose, claims, flags, and what an agent can never do (see Agents and the ceiling).
- A brief when a session starts, in a project whose
.reliquary.jsonnames a vault (the filereliquaryCLI commands read; see Use the CLI). Codex checks your flags for that vault, how many proposals are open and how long the oldest has waited, and the steps you hold, and tells you in a few lines. - A reminder after
git pushin that project: if the work changed something the vault records, Codex proposes an update. It only proposes; you approve it in your Inbox.
In any other project the plugin says nothing.
Without the plugin
Add the connection by hand, then sign in:
codex mcp add reliquary --url https://mcp.reliquary.redmage.cc/mcp
codex mcp login reliquary
Use the MCP URL your Connect page shows if it is different. Sign in and choose as in steps 3 and 4 above.
Check it
Ask Codex: Using Reliquary, list my vaults. It calls list_vaults and shows each vault with your role.
Change or remove it
- To change which vaults or access it has: revoke it on the Connections page, then run
codex mcp login reliquaryagain. - To remove it from Codex: uninstall the plugin in
/plugins, or runcodex mcp remove reliquaryif you added it by hand. Also revoke it on Connections.
Troubleshooting
/mcpshows reliquary as needing sign-in: runcodex mcp login reliquary. A revoked or expired connection asks you to sign in again.- No brief when a session starts: check that the project's
.reliquary.jsonnames a vault and that you trusted the hooks in/hooks. - It can't see a vault: you ticked other vaults when you allowed it, or you aren't a member. Revoke it and connect again with the vaults you want.
- Writes are refused: you chose read only, or you are a viewer in that vault, or the file is canon (use a proposal). See Canon, open and rules.
Any other refusal says what was being done, where and why, with a reference: see Errors and reference IDs.
For agents: this page as Markdown, and every page at /llms.txt.