Install your bridge

Start here: guided Context Relay setup

Context Relay lets ChatGPT read the visible history of one linked Codex task and permitted files from its local repository. You run the bridge on your own computer. This guide is for a first installation with Codex helping you through the steps. Experienced operators can go directly to the technical setup guide.

The tested user interface is Codex Desktop on macOS with its in-app browser. The bridge still needs a local codex executable internally to read Desktop task history through app-server. This does not establish standalone CLI onboarding as tested. Inspect the existing executable before installing another copy.

Start without prior chat context

The setup agent must treat this as a new installation, even if it recognizes the product name. Never reuse the author's domain, a previous chat's IDs, or an existing bridge's credentials. Examples are placeholders, not assigned settings.

Before creating anything, collect and confirm this worksheet:

Show the installation folder, release, local URL, MCP origin, OAuth audience, ChatGPT /mcp URL and optional separate website together. Ask the user to confirm this concrete proposal. Never derive the linked task from the browser tab: the operator must select the exact Codex task and its matching repository root. Save non-secret decisions in a private setup record so a new agent can resume.

For ongoing authentication, use the Auth0 trial transition checklist. The intended path is to keep your tenant on Free, not reinstall the plugin or create another trial account. Verify the connection again after the transition.

Check ChatGPT access before installing

OpenAI's developer guide lists Plus as eligible, while its Help Center guidance describes narrower availability. Check your actual ChatGPT web settings for Developer mode and custom app creation before upgrading or creating resources. Our live walkthrough used Pro. An eligible plan is not a completed Plus test.

1. Prepare your workspace and accounts

Use the platform guide to select macOS, Linux or Windows/WSL2 and its terminal commands before installing. Native Windows is not supported by the current bridge; Linux and WSL2 live acceptance remain unverified.

Use a dedicated local folder and Codex setup task named Context Relay: Codex & ChatGPT Collab. The folder holds the server code; the task is where you ask Codex to install and verify it. A ChatGPT Project is a separate, optional place for reusable instructions and sources. Creating either does not connect them.

Context Relay lets you use ChatGPT Chat for analysis separately from Codex coordination. It adds no model API billing. Each environment remains subject to its subscription's applicable allowances.

An account, a plugin, and a running MCP server are different things. Installing an Auth0 plugin does not create a bridge login; logging into ChatGPT in Codex's browser does not automatically share the Codex task. The authenticated MCP and explicit local task link establish that access.

Do not buy a plan, register a new domain, or install every suggested plugin just to begin. First have Codex check what you already have. See the version and account requirements.

GitHub context in both environments

For the combined workflow, set up the GitHub plugin/integration in both Codex and ChatGPT Chat. Use an existing authenticated integration where available; do not install a duplicate. Authentication in one environment does not establish access in the other, and signing into GitHub in a browser alone does not prove that the agent's GitHub tools are connected. If the integration is unavailable, the agent should explain the missing capability and provide manual setup steps. Local-only Context Relay use can continue without it.

1. In each environment, install or enable its available GitHub integration and complete its sign-in/authorization flow. Select only the intended repositories; complete organization approval if required. Keep credentials out of the chat.
2. Ask each agent to read a harmless known file from the intended repository and report the repository, branch and commit. Verify the result separately in Codex and ChatGPT. A plugin listing is not a successful access check.
3. For prompt drafting, queries, planning, reviews, building or fixing, combine relevant GitHub evidence with the linked Codex task and permitted local files. Label evidence LOCAL, TASK or GITHUB and preserve branch/revision and freshness. Unpublished local changes may differ from the remote branch; reconcile differences before proposing or applying changes.
4. To build or fix and commit directly to GitHub from ChatGPT Chat, its own GitHub integration must expose the necessary editing, branch creation, commit, push, pull-request and merge actions for the requested work and have repository write permission. Inspect actual tools before promising execution; permissions alone do not create a missing action. Agree on the target branch and authorized changes before writing. Read-only access can support a proposal or Codex handoff if write actions are unavailable.
5. Verify any authorized write through the resulting remote commit and diff. Report tests separately: a commit is not proof of tests, CI or deployment. Running tests requires an available executor or CI for that same revision.

The GitHub connection has separate permissions and does not inherit Context Relay's local path exclusions, secret filtering or task-link revocation. Keep secrets out of GitHub and scope its authorization independently. The bridge continues to provide local reads; it does not transfer tools or GitHub credentials between Codex and ChatGPT.

2. Give Codex the source and this starting prompt

Repository route: paste the prompt below into a new Codex setup task. Codex can clone the public repository into a new local folder.

Download route: download a source archive from the releases page, extract it to a new folder, and open that folder in Codex. Alternatively attach the archive if your Codex interface supports it and ask Codex to extract and inspect it. If attachments are unavailable, supply the extracted folder's absolute path. A ZIP is source code, not a running installer; the same build and account setup follow. If it has no Git metadata, verify its release provenance without inventing a commit.

Copy this prompt; replace the bracketed source line if you use a download:

Help me install and verify Context Relay: Codex & ChatGPT Collab on this computer.
Assume this is a fresh chat with no prior setup context. Follow the configuration
worksheet in docs/getting-started.md. Do not reuse anyone else's domain or IDs.
Start with read-only preflight. Complete one checkpoint, report the evidence,
and wait for me to say "next" before starting another checkpoint.

Source: https://github.com/digitalpilipinas/context-relay
[If downloaded instead: use my attached source archive or extracted folder at
ABSOLUTE_PATH. Inspect it and identify its release before running anything.]

Read AGENTS.md, README.md, docs/setup.md and SECURITY.md from that source.
Use docs/getting-started.md from the public repository for this guided workflow
if the chosen older release does not include it. Release source governs runtime
behavior; report differences instead of assuming newer features exist.
Detect macOS, Linux or Windows/WSL2 and follow docs/platform-setup.md from the
public repository. Use the right terminal and keep the Codex task and repository
in the same environment as the bridge. Native Windows is unsupported; report
Linux/WSL2 acceptance as unverified until tested there.
Check existing software, accounts, installed
plugins and actually available tools. Explain missing requirements in plain
language. Prefer a published release and record the exact version/revision. Record the
onboarding documentation branch and commit separately. If the requested docs
are not on the default branch, retrieve that exact revision; do not silently
substitute older instructions. Before executing setup commands, verify that the
guide's commands, package scripts and configuration options are supported by
the selected release or archive. If compatibility cannot be established, stop
that checkpoint and explain the mismatch; use matching documentation or agree
on a compatible release before continuing. Replace example domains and paths only after
agreeing on my own settings. The tested interface is Codex Desktop on macOS
with its in-app browser; standalone CLI onboarding remains unverified.

For combined local/cloud work, verify the GitHub plugin/integration separately
in Codex and ChatGPT Chat. Guide me through missing installation, authentication
and repository selection, then verify a harmless repository read in each.
Use GitHub context alongside task/local evidence for prompts, queries, plans,
builds and fixes. Keep their revisions distinct. Before direct GitHub changes
from ChatGPT, verify its actual write actions and my authorized branch/scope.
Never test writes by creating an unrequested commit or claim a commit proves tests.

Use a new setup folder and preserve any existing bridge, credentials, tunnels,
ChatGPT projects and local changes. Before creating cloud resources, agree with
me on the final app name, MCP hostname and optional product website hostname.
Show the public origin, Auth0 API identifier and ChatGPT /mcp URL together;
check spelling, trailing slash and domain ownership. Reuse matching resources
already created for this setup instead of creating duplicates after a pause.

Do the authorized setup autonomously where your tools support it. At each
milestone tell me what passed, what you are doing next, and whether I need to
act. For a manual step, give the exact page, field or local file, expected
result, and how I should tell you it is complete. Keep credential values out
of chat, logs, command history, screenshots and Git. Respect required sign-in,
password, consent and security-approval handoffs; never bypass them.

Keep context access disabled until authenticated synthetic checks succeed.
Then use a synthetic task and sample Git repository to test permitted reads,
individually approved untracked files, blocked/ignored files and revocation.
Verify the actual ChatGPT tools and status card separately from source tests.
Do not expose my real project until we have agreed on its exact task and scope.

Optionally prepare a ChatGPT Project named Context Relay: Codex & ChatGPT Collab.
Generate and explain the project-source package; preserve existing instructions
and source mappings. Manual project creation/upload must remain possible.
Do not claim a source upload installs tools or transfers this chat automatically.

Finish with actual PASS / FAIL / NOT RUN results, the private start/stop commands,
the installed version, remaining manual steps, and how to renew or revoke links.
Do not describe the installation as working until live authenticated calls pass.

This prompt is a setup request, not blanket permission to publish private data, buy services, delete resources, or bypass the host's approval rules. If software or accounts are missing, Codex should prepare the exact next step and request only the necessary user action.

3. Work through the checkpoints

Stop after each checkpoint and wait for “next”. If a check fails, preserve the last working state, explain the failure, and retry only that checkpoint after its cause is addressed. Never fix a failure by broadening access.

Codex should use the technical guide and keep one short private setup record outside the source checkout. Record resource names/IDs, version, port, completed checks and the next step; never put passwords, tokens, task excerpts or private file contents in that record. Keep credentials in their designated private files or provider settings.

Example progress update:

The build and tests passed. Next I am preparing your Auth0 connection. Your action: sign in to the Auth0 dashboard in the open tab. Use your own account; do not send me the password. Tell me “signed in” when the dashboard appears. I will verify the tenant and continue from this checkpoint.

For a token handoff, specify the exact private file and whether it expects only the token value, not the displayed shell command. Never ask users to paste secrets into the conversation. After “done,” verify the result without displaying the credential. If the browser/session was lost, reopen the exact needed page, retain it for the user's action when supported, and resume; do not restart setup.

If a tool fails, report the failed action, what changed (if anything), and the next safe step. Check for partial creation before retrying. A missing optional plugin is not a reason to abandon manual setup. A missing authentication step is not a successful installation.

4. Optional ChatGPT Project

The suggested project name is Context Relay: Codex & ChatGPT Collab. You may instead use an existing project. Codex's setup task and this ChatGPT Project are separate; neither supplies access to the other by itself.

After installing the source, run this from its app/ directory:

corepack pnpm project-package ../context-relay-project-sources

The destination must not already exist; the command deliberately refuses to overwrite it. If it exists, review that package or choose a new output name. The generated package includes an instruction addendum, collaboration guide, prompt templates, return-handoff template, five workflow documents and a source index. Review them before uploading. Follow project setup to add the instructions and selected documents manually, or use available browser assistance. Retain unrelated project instructions and source mappings.

Uploaded sources are snapshots. Read changing code and task history through MCP. For the return journey, transfer the Markdown handoff to the intended Codex task; Codex refreshes local evidence before implementing and testing. There is no automatic task injection or shared tool access.

5. What “ready” means and how to resume tomorrow

Ready means the installed instance has passed live authenticated checks, one synthetic task-history/file retrieval, access denials and revocation. A successful build, Auth0 login, tunnel connection or plugin listing alone is insufficient. Use the full verification checklist for feature acceptance.

Keep the private start/stop instructions supplied by Codex. Both the bridge and tunnel must run while ChatGPT reads context. Startup is manual in this release. A task link expires after 24 hours: create a fresh link when needed, not a new Auth0 app or tunnel. Never share an existing operator's private endpoint or login as a public demo. Refer to troubleshooting with redacted error messages if a checkpoint fails.

For everyday use after installation, see Using Context Relay.

Run your own bridge

The verified onboarding interface is Codex Desktop on macOS with its in-app browser. Standalone Codex CLI onboarding is unverified. The local codex executable remains a runtime dependency because the bridge launches codex app-server to retrieve the linked Desktop task's history.

New to MCP setup? Start with the guided setup and copy-ready Codex prompt. It explains required accounts versus optional plugins and who handles each step. For advanced users, see platform installation commands for macOS, Linux and Windows via WSL2. All Bash commands below run in the bridge host environment; on Windows that means the WSL Linux terminal, not PowerShell.

Start with the requirements and security boundaries. All domains, IDs and paths below are placeholders. No author-owned endpoint or authentication is included.

Context Relay lets you use ChatGPT Chat for analysis separately from Codex coordination. It adds no model API billing. Each environment remains subject to its subscription's applicable allowances.

0. Agree on names and URLs before creating resources

Use your own domain in all examples. Keep these settings distinct:

For this pinned adapter, the API identifier must match the advertised MCP resource (origin plus trailing slash). Do not use the website URL as the MCP origin or paste /mcp into BRIDGE_PUBLIC_URL. An API identifier is an OAuth audience, not a website to visit. Auth0 does not let you edit an existing API's identifier; check spelling before creating it. Renaming its display name does not change its identifier. Inspect existing setup resources before creating more.

For a second installation, use a separate port, configuration, tunnel/hostname and OAuth audience. The current runtime stores grants under the OS user's ~/.config/codex-pro-bridge/links; a new checkout or plugin name alone does not isolate grants. Grants check the owner subject and host, not the public origin. Use a distinct bridge login subject for the test instance (or a separate OS user with its own Codex task data), and keep context disabled until it is verified. Do not copy the original instance's credentials or grants into public source.

1. Install and verify the source

git --no-lazy-fetch --version
git clone --branch v0.4.0 --depth 1 https://github.com/digitalpilipinas/context-relay.git
cd context-relay/app
corepack pnpm install --frozen-lockfile
corepack pnpm typecheck
corepack pnpm test
corepack pnpm build

These commands pin the published v0.4.0 source; detached HEAD is expected for a release tag. If the destination folder already exists, inspect it instead of cloning over it. For a downloaded release archive, extract it, open a terminal in its app/ directory, and start with the pnpm commands above. Record its source and version; do not claim Git revision verification if .git is absent.

Use Node and pnpm versions compatible with package.json. Ensure git, codex and cloudflared are on the PATH used to launch the server. codex --version and codex app-server --help should work. This requires the local Codex task store; a GitHub repository alone is not task history.

Use Git 2.48 or newer; the --no-lazy-fetch probe must succeed on the server's PATH. The bridge passes this option explicitly so unsupported versions fail before reading repository content, rather than silently ignoring an environment guard. See the Git option documentation.

2. Create your own Auth0 configuration

This implementation uses a predefined OAuth client and a standard user login. It does not implement local one-time-code pairing or a public unauthenticated mode. See OpenAI's OAuth requirements for host registration and callback rules.

In your Auth0 tenant:

1. Create an API with identifier https://bridge.example.com/, replacing the hostname with your own bridge's future public hostname. Use RS256 signing.
2. Add permissions bridge:probe and bridge:context. The first is for connection/workflow tools; the second is additionally required for context.
3. Create a dedicated Regular Web Application, with a descriptive name such as ChatGPT Desktop Context Bridge. Configure the authorization-code flow with PKCE (S256) and a token authentication method supported by the ChatGPT connection. Do not grant Management API or machine-to-machine access.
4. Enable the login connection you intend to use for this client, then create or register your bridge user through that connection. Signing into the Auth0 administration dashboard does not create this application user.
5. In Auth0's user details, obtain that user's exact user_id/token sub for your private AUTH0_OWNER_SUBJECT. Do not use your email address, client ID, or dashboard administrator ID in its place.
6. When ChatGPT shows your connection's callback URI in step 5 below, add that exact URI to this Auth0 client's allowed callbacks. Do not use wildcards or another person's callback. Keep the client ID/secret private in the connection settings if the selected method requires them.

Use the tenant's default hostname; an Auth0 custom domain is unnecessary for this starter. Use a normal database connection for the simplest setup. If you choose social login instead, configure it for this application separately. Provider UI labels and registration options can change; check their current documentation rather than weakening authentication to resolve a setup issue.

With per-application API authorization, grant only the intended client user-delegated access to bridge:probe and bridge:context; verify both were saved. Do not enable client-credentials access. A provider-created test application is not the Regular Web Application used by ChatGPT and should not be authorized as a workaround.

3. Configure the bridge locally

From app/, create a private .env:

test -e .env || test -L .env || (umask 077; cp .env.example .env)
chmod 600 .env

Use a regular local file, not a symlink. If .env already existed, the copy step preserves its contents; inspect its purpose before editing. The checked-in example has empty required Auth0 fields and cannot start a working server. Startup performs authorization-server discovery, so invented tenant domains are not a valid live smoke test. Edit that file locally. Do not paste credentials or token contents into an AI conversation, public issue, screenshot or shell command history.

The trailing slash in the API identifier matters. Compare the advertised protected resource with the configured audience; do not fix a mismatch by disabling audience checks. Auth0's issuer is the canonical tenant URL ending in /, not the bridge URL. No OAuth client secret belongs in this .env.

corepack pnpm run doctor
corepack pnpm start

doctor validates configuration syntax only. It does not verify login, the tunnel or a ChatGPT model. start must run from app/ so production assets are resolved correctly. Keep this terminal open.

4. Configure a Cloudflare Tunnel

Use your own Cloudflare account and domain. Create a dashboard-managed tunnel and route a dedicated hostname to http://127.0.0.1:3487 (or your selected port), following Cloudflare's setup guide. No port forwarding or separate application VM is needed for this arrangement.

Install cloudflared using Cloudflare's platform instructions. Keep its tunnel token in an owner-readable file outside the checkout, for example ~/.config/codex-pro-bridge/tunnel.token. This is a credential: use a local editor or credential manager to save it, then restrict the file to mode 600 and its parent directory to 700. Do not substitute the token text into a command. A second terminal can run:

cloudflared tunnel --no-autoupdate run \
  --token-file "$HOME/.config/codex-pro-bridge/tunnel.token"

Expose the production server, never pnpm dev or its devtools. Discovery and card assets must be reachable by ChatGPT; MCP calls remain protected by the bridge's OAuth. An extra interactive Cloudflare Access login in front of this endpoint will require additional integration not provided here.

Replace the hostname in these checks with your own:

curl -fsS https://bridge.example.com/healthz
curl -fsS https://bridge.example.com/.well-known/oauth-protected-resource
curl -sS -o /dev/null -w '%{http_code}\n' \
  -X POST https://bridge.example.com/mcp \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Expect a ready health response, protected-resource metadata, and 401 for the unauthenticated MCP request. None proves that authenticated tools work.

5. Connect in ChatGPT

In your eligible ChatGPT account, enable developer mode if required and create a custom MCP connection pointing to https://bridge.example.com/mcp. Choose OAuth and provide your own predefined client's details as required. Use the callback URI shown there to finish the Auth0 allowlist in step 2.

Authenticate with your bridge user and approve the requested scope. Select the connection in a chat and ask it to call get-connection-check. Verify an actual tool response and status card. Run the negative checks in verification before linking real context. A successful card does not verify the selected model, local data access or code execution.

6. Link exactly one task and repository

Set BRIDGE_CONTEXT_ENABLED=true in the private .env, restart the production bridge and refresh the ChatGPT connection's tool list. Reauthorize if needed so the token includes both bridge:probe and bridge:context.

From app/, use the real Codex task ID supplied by Codex and the exact Git root that task uses. Do not substitute a ChatGPT conversation URL/ID or a different checkout:

corepack pnpm context link TASK_ID /absolute/path/to/repository

The repository needs a HEAD commit. By default the link includes eligible tracked files. To additionally allow specific nonignored untracked files, list their repository-relative paths after the root:

corepack pnpm context link TASK_ID /absolute/path/to/repository docs/draft.md

To narrow the same link to selected files and directories:

corepack pnpm context link TASK_ID /absolute/path/to/repository docs/draft.md \
  --allow AGENTS.md --allow src/ --allow tests/ --allow docs/

--allow is repeatable. Entries are literal repository-relative file paths, or directory prefixes ending in /; wildcards, traversal and empty entries are rejected. src/ does not include src-other/. Include applicable AGENTS.md paths explicitly if they sit outside your selected directories. A selected directory does not automatically approve its untracked files: those still need individual positional arguments. Git-ignored and secret files stay excluded.

Omitting --allow preserves the original eligible-file scope, including for existing version-1 grants. To restrict an existing link, create a narrower one, switch the chat to it and revoke the old link. An older server rejects grants containing the new field; when rolling back, revoke those restricted links rather than deleting their restriction field. File limits do not restrict which visible messages in the linked task can be retrieved. Review that task too.

Use configuration documentation to share variable names and requirements without values. .env.example is intentionally blocked by the bridge even though this repository includes a placeholder copy for local setup.

The command verifies the task/root match and returns linkId and expiresAt. Supply that link ID to your authenticated ChatGPT chat. Ask it to call read-linked-context with operation: overview, then request only relevant messages, files, instructions or changes. Each response carries provenance and freshness information. A link's possession alone does not bypass OAuth.

corepack pnpm context status LINK_ID
corepack pnpm context unlink LINK_ID

Links expire after 24 hours. Create a fresh one when required; you do not need to recreate the Auth0 tenant or tunnel daily. Their token policies are separate. Conversation cursors last up to ten minutes in process memory; restart an expired read instead of reusing its cursor. Restarting the bridge clears those snapshots but does not delete on-disk, unexpired link grants.

Troubleshooting and shutdown

To stop access, revoke relevant links and stop the bridge/tunnel with Ctrl+C. Disconnect the custom app in ChatGPT when retiring the instance. This guide does not install automatic startup, change DNS for unrelated services or rotate credentials for you. If credentials are exposed, rotate them at the provider; deleting a Git file does not revoke a credential.

Lessons from guided onboarding

• Use corepack pnpm run doctor. The explicit run selects this project's script, rather than pnpm's own command. A successful doctor check is not authentication.
• Signing into the Auth0 dashboard with Google does not create the application's bridge user. Sign in through the bridge application's enabled connection using the intended owner identity. A reused session for another owner can be rejected.
• After enabling context scope, refresh the connector's actions, reconnect to authorize the changed scope, and retry in a fresh ChatGPT conversation if needed. An installed plugin or stale settings page does not prove the new tools work.
• Save only the tunnel token in the designated private file, not the entire provider installation command. Verify file existence and permissions without printing its contents. If a credential is pasted into chat, rotate it with the provider before continuing; removing the message alone does not revoke it.
• A plugin stays installed when its local server or tunnel stops. On failure, check the local health endpoint, then tunnel connectivity, then public health, then an authenticated tool call. A 502 alone does not identify the cause. This setup does not install automatic startup. Explain how to restart both processes, and verify them again after sleep, logout or reboot.

After the Auth0 trial ends

Auth0 says the Free plan activates automatically after its trial expires, with continued access to Free-plan features. Context Relay's documented single-owner configuration targets those features. Keep the existing tenant, application, API and bridge login; a new account or plugin is not the normal fallback. Auth0 trial transition.

Before expiration, inspect the tenant's enabled features and current quotas. If a trial-only feature was enabled, identify whether the bridge depends on it and replace that dependency with a supported Free-plan configuration. Do not weaken authentication or disable owner, audience or scope checks to restore access.

After transition, record actual results for:

1. A fresh login as the configured bridge owner.
2. An authenticated connection check.
3. A permitted synthetic file read through a valid task link.
4. Rejection of a revoked synthetic link.

Until performed on the Free plan, label these checks NOT RUN. A test during the trial does not establish post-trial operation. If a check fails, investigate the specific feature, quota or authentication error before changing configuration. Reinstalling a plugin does not reset provider quotas. Creating another account to restart a trial is not the recommended recovery path.

Optional GitHub build and fix workflow

ChatGPT can use its own authenticated GitHub integration to edit remote files, create branches, commit and push, open pull requests, and merge when the needed actions are available and the user and repository policies authorize them. Verify those capabilities in the current ChatGPT interface before promising a write. Context Relay supplies permitted local files and the linked task history; it does not supply GitHub write tools or bypass branch protections.

Before changing remote code, compare the local evidence with the target remote revision. Afterward, verify the remote diff and report actual tests or CI results. Reconcile the local checkout separately, preserving unpublished local work.