Add a referral program with OpenAI Codex
Codex reads AGENTS.md from the repository root down to the working directory, and the CLI, the IDE extension, and the desktop app share one MCP configuration. Give it both, and it can read your referral configuration and write the signup tracking.
Give Codex the RefRef rules
The rules tell the agent where each part of a referral integration belongs: the landing script in the browser, one signup call where your backend creates the account, and the API key only on the server. Save it as AGENTS.md in the repository root, or add its text to your existing AGENTS.md.
Codex reads every AGENTS.md from the repository root down to the folder where it runs, joins them, and caps the total at 32 KiB by default. A nested AGENTS.md can add rules for one package; an AGENTS.override.md replaces the file of its folder. The RefRef rules use about 4.5 KiB, so they fit beside a long project file.
# RefRef referral tracking
This app uses RefRef (https://refref.ai) for its referral program. Follow these rules when you add or change referral code.
## Configuration
- Server-only secrets: `REFREF_API_KEY` (a Workspace API key), `REFREF_PROJECT_ID`, and `REFREF_PROGRAM_ID`.
- `REFREF_API_URL` defaults to `https://api.refref.ai`, and `REFREF_ASSETS_URL` to `https://assets.refref.ai`. Read both from configuration, so that a Sandbox or local environment can change them.
- Never put `REFREF_API_KEY` in browser code, in a public variable (`NEXT_PUBLIC_*`, `VITE_*`), in a prompt, in a log, or in a commit.
- Every RefRef call is a backend `POST` with a JSON body that contains `projectId`, and the header `X-Api-Key`. The current schemas are at `GET $REFREF_API_URL/openapi`.The start of the file. Open the whole file.
Or fetch it from the command line: curl -fsSL https://refref.ai/agents/codex/rules.md >> AGENTS.md (>> appends to an existing file)
Connect Codex to RefRef MCP
Optional. With the MCP server, Codex can read your Workspaces, Projects, and Programs, and prepare configuration changes for you to approve in the Console. It never sends signups: that is the app code from the rules. See the MCP reference for scopes and approvals.
Configuration: ~/.codex/config.toml, or .codex/config.toml in a trusted project
[mcp_servers.refref]
url = "https://mcp.refref.ai/mcp"Or with the CLI
codex mcp add refref --url https://mcp.refref.ai/mcpSign in
codex mcp login refref --scopes mcp:read,mcp:write,offline_access opens the browser. Sign in with your RefRef Console account. Use --no-browser on a remote machine. The connection uses your Console sign-in, never a Workspace API key.
Check it
codex mcp list
- codex mcp add starts the sign-in at once when the server supports OAuth. Run codex mcp login later to sign in again or to change scopes.
- mcp:write is offered only to Workspace owners and admins. Read-only work needs mcp:read.
- AGENTS.md files together are capped at 32 KiB by default (project_doc_max_bytes).
1. Configure the Program through MCP
Optional. Needs the refref MCP server and a Console account with the owner or admin role.
Use the refref MCP server. Call get_workflow with workflow="configuration", then list_workspaces. Ask me to choose the Workspace, and use only the Sandbox Project that I confirm. Read its Programs and rules. Propose a referral Program that gives the referrer a reward when a referred person signs up. Ask me for the reward, the currency, and the limits; do not assume them. Return the proposal and its review link. Do not approve or apply it.2. Add referral tracking to the signup
The rehearsal ran this prompt with "the project instructions" in place of the rules file name, on a Node app whose tests use node --test.
Add RefRef referral tracking to the signup of this app. Follow the RefRef rules in AGENTS.md. Configuration comes from environment variables. Do not add dependencies. Add focused tests and run them.3. Review the change before you merge it
Run it in a new session, so that the agent reads the diff with fresh context.
Review the RefRef integration in the current diff against AGENTS.md. Check each item of "Tests to write" and "Do not". Confirm that the signup is sent once, only where the account is created, and that REFREF_API_KEY never reaches the browser. List each problem with its file and line. Change nothing.Set REFREF_API_KEY, REFREF_PROJECT_ID, and REFREF_PROGRAM_ID in your backend environment. The integration reference has each call, and the auth recipes cover email verification, magic links, and hosted login.
What we ran, and what happened
Each check below ran end to end. A Reward that the journey earns is an accounting result, not a delivered payment.
- passed · 2026-10-20The MCP configuration is the one that Codex writes
- codex mcp add refref --url https://mcp.refref.ai/mcp (codex-cli 0.163.0) wrote exactly the [mcp_servers.refref] table shown above, and started the OAuth sign-in at once.
- passed · 2026-10-20OAuth sign-in and a read tool call against a RefRef stack
- Against a disposable RefRef stack: codex mcp login --no-browser --scopes mcp:read,offline_access, consent in Chrome as a Workspace owner, and the callback URL pasted back. codex exec in a read-only sandbox then listed both Workspaces with the Live and Sandbox Projects. Changed nothing.
- passed · 2026-10-20Prompt 2 and the rules file produce a working signup integration
- Codex (codex-cli 0.163.0, workspace-write sandbox) ran prompt 2 with the rules as AGENTS.md, on a bare Node signup app. It moved the RefRef calls into a referral tracker in refref.mjs that the server receives, retried a failed delivery with the identical body, and wrote three tests in server.test.mjs, one of them for HTTP and network failures. Against a disposable RefRef stack: B followed A's link in Chrome and signed up, and the referral named A as referrer and B as referee; B's next sign-in sent no second signup; an organic signup made no referral; no page contained the API key; the signup succeeded with RefRef unreachable.
01Does the same AGENTS.md work in other agents?
Yes. Cursor, GitHub Copilot, Windsurf, and Claude Code (when there is no CLAUDE.md) also read AGENTS.md, so one file can serve a team that uses several agents.
02Which sandbox does Codex need for this work?
workspace-write. In the rehearsal, codex exec ran prompt 2 in that sandbox: it can edit the repository and run tests, but it cannot reach other folders.
Official references
Start with a Sandbox Project
Create a RefRef account, add a Project, and get the keys that the Codex prompts need. Sandbox data never mixes with live data.