ContextUsing Context Relay
Already installed? Start here. This guide describes the five-workflow runtime on main and v0.4.0. An installed plugin makes tools available; it does not choose a Codex task, launch a browser or automatically share your history.
1. Check the connection
Purpose: reuse your installation without repeating setup. Ask Codex to check your existing bridge and tunnel, the installed version, and whether context reads are enabled. Keep private settings outside the checkout. In ChatGPT, select your Context Relay connection and run its connection check.
Success: an authenticated response and the correct host. A healthy web address alone does not prove authenticated access. If either process is stopped, follow your private start instructions. Do not create replacement accounts or tunnels. See troubleshooting.
2. Choose the exact task and repository
Use this prompt in the Codex Desktop task you want to consult about:
Help me consult ChatGPT using my installed Context Relay about [goal].
Identify this Codex task and its exact repository root. Check my existing bridge
and create or reuse a valid scoped link. Show the files and any individual
untracked paths that need my approval. Keep ignored and secret files excluded.
Prepare a brief with the goal, acceptance criteria and returned link ID.
If browser assistance is available, help me open ChatGPT and submit that brief;
otherwise give me the brief and manual steps. Verify retrieval before claiming
ChatGPT has the context. Do not change my existing authentication or installation.
Replace [goal] with your actual question. Browser assistance is an agent action
using separate tools, not an MCP feature. The task and local Git root must match.
A worktree is a separate root; do not silently substitute another checkout.
Approval: eligible tracked files are readable within the link scope. Individually approve nonignored untracked documents you want to share. Directory scope does not approve all untracked files. Never approve secrets for sharing.
For manual operation, from the bridge's app/ directory:
corepack pnpm context link TASK_ID /absolute/path/to/repository
To include one approved untracked document and limit eligible paths:
corepack pnpm context link TASK_ID /absolute/path/to/repository docs/draft.md --allow AGENTS.md --allow src/ --allow docs/
Success: the command validates the task/root and returns linkId and
expiresAt. Ask Codex to supply the actual values, not invented placeholders.
Keep links in your authorized conversation, never in public website URLs.
3. Ask ChatGPT to read the evidence
Codex can fill in the link for you. If you are transferring it manually, use:
Use Context Relay with [the link ID supplied by Codex]. Read overview first.
For [goal], retrieve relevant task messages, files, diffs and applicable project
instructions. Keep TASK, LOCAL and any separately retrieved GITHUB evidence
identified with timestamps and revisions. Tell me if a read is missing or denied.
Use the relevant review, build-fix, consult, prompt or project-setup workflow.
Do not claim to have read content that was not returned by a tool.
Return findings, proposed actions and actual PASS / FAIL / NOT RUN checks.
Success: actual context-tool results identify the intended task/root and relevant source evidence. A plugin selection or a model's assertion is insufficient. The overview does not deliver the entire repository or task history. Further reads are on demand and bounded. Missing history does not mean complete context.
4. Continue the same conversation
You usually do not need to paste the same valid link with every follow-up. Ask ChatGPT to reuse the supplied link and refresh relevant evidence before continuing. It must call the tools to see new local changes; earlier messages are not a live mirror. If the link is no longer available in the conversation, supply it again.
Continue using the Context Relay link already supplied in this conversation.
Refresh the relevant source and task evidence before answering [next question].
If the link has expired or access fails, explain the gap and ask me to have Codex
prepare a refreshed handoff. Do not use an old snapshot as current evidence.
Links last 24 hours. From app/, inspect or revoke one:
corepack pnpm context status LINK_ID
corepack pnpm context unlink LINK_ID
To renew access, create a new scoped link and approve its untracked paths again. Do not recreate Auth0 or Cloudflare resources. Revocation prevents future reads; it cannot remove information already supplied to ChatGPT.
5. Return the report to Codex
Copy the report into the original Codex task. Include its task identity, root, branch/revision, files, evidence timestamps, recommendations and actual validation. Use the return-handoff template.
Review this returned Context Relay report against the current task and files.
Refresh the repository state and reconcile stale evidence. Implement only the
changes within my authorized scope, run relevant checks, and report what actually
passed, failed or was not run. Do not treat a suggested command or a GitHub commit
as proof that tests or deployment passed.
[Paste the report here.]
ChatGPT can use GitHub write actions only when its separately authenticated integration exposes them and you authorize the changes. Remote commits do not update the local checkout automatically. Downloaded artifacts need an explicit local import and validation step. Work-specific compatibility and export of Work history are not established by this release's tested Codex Desktop path.