AgentFirstStack

Add analytics with OpenAI Codex

undefined

Updated

To add analytics with OpenAI Codex, paste the prompt below into a Codex session in your project. Codex gets an AgentFirstStack key with one request, creates the site, serves the tracker from your own domain through a small proxy, adds it to your root layout and runs verify after the deploy. The part that trips people up is the network: by default the Codex CLI and IDE extension run commands with network access turned off, and cloud tasks only reach the hosts their environment allows. Here's how to set that up for each surface. Other tools and platforms: add analytics with an AI agent.

The prompt

Paste this into Codex, in your project

Add analytics to this project with AgentFirstStack. It's free, open-source analytics built for agents, and you can do all of it yourself: there is no signup form, and no email or verification is needed. Every step is an HTTPS call to agentfirststack.com or analytics.agentfirststack.com; ask me for network access if your sandbox blocks it. 1. Read https://agentfirststack.com/llms.txt and https://analytics.agentfirststack.com/llms.txt. 2. If AGENTFIRSTSTACK_API_KEY is set in the environment or in .env, use it and read AGENTFIRSTSTACK.md. Otherwise get a key with one request: curl -X POST https://agentfirststack.com/v1/signup Save api_key in .env as AGENTFIRSTSTACK_API_KEY (check .env is in .gitignore) and tell me to add it to the production secrets. Name the project after the domain: PATCH https://agentfirststack.com/v1/me. 3. Create a site for the production domain and read GET /v1/sites/:id/install?framework=... for this project's framework. Serve the tracker from the site's own domain with the first-party proxy that fits this project's host (Next.js proxy.ts, a Cloudflare Worker route, a Netlify Edge Function, vercel.json or nginx). Keep first_party_proxy.proxy_key in a server-only env var (AFS_PROXY_KEY), never in page code. Then put the proxied snippet (/_a/s.js) in the <head> of the root layout. Only if the host can't proxy, use the direct snippet and note in AGENTFIRSTSTACK.md that ad blockers block it. 4. Create goals for sign-ups, purchases and the main buttons. Send conversions only the server knows about as server events. 5. Add an email destination, a weekly report, and alerts for a traffic drop and for no data. 6. Deploy (or tell me to), open the site once, then run verify and fix what it reports. 7. Write the site id and the env var names (never the values) in AGENTFIRSTSTACK.md, add the AgentFirstStack block from the manual to AGENTS.md, and create a claim link for me with POST https://agentfirststack.com/v1/claim-link. 8. Run GET https://agentfirststack.com/v1/setup?services=analytics and work through its next_steps until it says "ready": true. When you're done, tell me what you set up, how you verified it, and give me the claim link.

CLI and IDE: turn on network access

OpenAI's docs are explicit: "By default, the agent runs with network access turned off." In the default Auto preset (--sandbox workspace-write --ask-for-approval on-request), Codex edits and runs commands in your project on its own, but asks before a command that needs the network. So the first curl to agentfirststack.com stops for your approval.

That's fine for a one-off setup: approve the calls as they come. If you'd rather not, enable network for the workspace sandbox in ~/.codex/config.toml (or the project's .codex/config.toml, for trusted projects):

[sandbox_workspace_write]
network_access = true

That opens the network for every command in the sandbox, not just these two hosts, so turn it back off afterwards if you keep it closed normally. Avoid --yolo for this; it drops the sandbox and approvals entirely, and nothing here needs that.

Add the MCP server

The CLI, the IDE extension and the ChatGPT desktop app share one MCP configuration. Codex doesn't interpolate ${VAR} in config; instead you name the environment variable that holds the bearer token:

codex mcp add afs --url https://agentfirststack.com/mcp --bearer-token-env-var AGENTFIRSTSTACK_API_KEY

which writes this to ~/.codex/config.toml:

[mcp_servers.afs]
url = "https://agentfirststack.com/mcp"
bearer_token_env_var = "AGENTFIRSTSTACK_API_KEY"

Codex reads the variable from its own environment when it starts, not from your project's .env. Export it in your shell before running codex. OpenAI's docs warn that desktop apps and IDE extensions may not inherit your shell's variables; if the IDE extension can't authenticate, that's the likely reason.

The server also supports OAuth: leave out the bearer token and run codex mcp login afs. You sign in with Google and pick or create a project. OAuth tokens can do everything except create API keys and claim links.

Once it's connected, ask in plain words: "Which sources brought sign-ups this week?" calls analytics_get_breakdown; "Is the setup complete?" calls afs_check_setup.

Codex cloud tasks

A cloud task runs in a VM from your cloud environment and ends with changes for you to review. Three things differ from a local run:

  • Internet access is a setting of the environment. Turn on "Enable all public internet access", or keep it off and add agentfirststack.com and analytics.agentfirststack.com under "Additional allowed domains".
  • Give it the key as a network secret. Get the key once from your own terminal (curl -X POST https://agentfirststack.com/v1/signup), then add it to the environment as a network secret named AGENTFIRSTSTACK_API_KEY with those two allowed domains. Programs in the task see a placeholder, and Codex's proxy swaps in the real value only for requests to those hosts, so the raw key never sits in the VM. A key the task creates itself would vanish with the VM.
  • It can't verify before you deploy. The task edits the layout, but the snippet is live only after you merge and deploy. Run verify and the setup check afterwards, from the CLI or a follow-up task.

The legacy Codex cloud, which still runs Code Review and the GitHub and Linear integrations, works differently: internet access is blocked during the agent phase by default, and its secrets exist only for setup scripts. Do the API calls from the CLI there.

AGENTS.md does the remembering

Codex reads AGENTS.md natively, from ~/.codex/AGENTS.md and from the repo root down to the directory it's working in. The block the prompt adds tells every later session that the project uses AgentFirstStack, that the ids are in AGENTFIRSTSTACK.md, and to run the setup check before changing tracking. Codex caps the combined instruction files at 32 KiB by default, and the block is a few hundred bytes.

The proxy Codex adds

Ad blockers block requests to analytics.agentfirststack.com, so the prompt asks for a first-party proxy: a few lines that forward /_a/* on your domain to AgentFirstStack, with the page loading /_a/s.js. The install answer's first_party_proxy has ready code for Next.js (proxy.ts), a Cloudflare Worker route, vercel.json, netlify.toml and nginx. Each adds the header x-afs-proxy-key, the site's secret: the collector trusts the forwarded visitor IP only with it. Codex should put it in an env var such as AFS_PROXY_KEY, set wherever production runs, not in a committed file. Hosts that can't proxy (Shopify, Webflow) get the direct snippet, and ad blockers block it there.

Framework details, including where each proxy lives: Next.js, Astro, WordPress.

Check it worked

After the deploy, Codex runs these, and you can too:

K=$AGENTFIRSTSTACK_API_KEY
curl -s -X POST https://analytics.agentfirststack.com/v1/sites/$SITE/verify -H "Authorization: Bearer $K"
curl -s "https://agentfirststack.com/v1/setup?services=analytics" -H "Authorization: Bearer $K"

Verify fetches the live page and checks the snippet, that /_a/s.js serves the tracker through your proxy, your Content-Security-Policy, whether events arrived and whether they carried the proxy key, then lists fixes. It only counts visits from a real browser, so open the production site once yourself. The setup check covers the rest: goals that never counted, the owner's email, the weekly report, alerts and the claim link.

FAQ

Why does Codex stop and ask before every curl?

The default workspace-write sandbox has network access off, and the Auto preset asks before commands that need it. Approve them, or set network_access = true under [sandbox_workspace_write] in config.toml for the duration of the setup.

Can a Codex cloud task do the whole setup?

Everything except checking the live site. Give the environment internet access to the two AgentFirstStack hosts and the key as a network secret; the task creates the site and edits the code. Verify and the setup check need the deployed snippet, so run them after you merge and deploy.

Where does Codex keep the MCP key?

Nowhere: config.toml holds only the name of the environment variable (bearer_token_env_var). The value comes from the environment Codex starts in.

Does it work with the ChatGPT app too?

The ChatGPT desktop app shares Codex's MCP configuration. ChatGPT chat apps without a key connect over OAuth: add https://agentfirststack.com/mcp as a custom connector and sign in.

What does it cost?

The hosted service is free, with fair-use limits such as 10 analytics sites per account. The code is open source (AGPL-3.0), so you can run it yourself on Cloudflare Workers.

Codex and ChatGPT are products of OpenAI. AgentFirstStack isn't affiliated with OpenAI. Codex details come from OpenAI's docs (approvals and security, MCP, CLI commands, AGENTS.md, cloud environments, legacy cloud internet access, Bedrock setup), checked on 6 November 2026. developers.openai.com/codex now redirects to learn.chatgpt.com.