FreeRide
← Back to docs

Codex

FreeRide works in Codex: the Codex app, the Codex CLI, and Work mode in the ChatGPT desktop app. In a repo that's set up, Codex gets a briefing on the project, logs what it builds and keeps the docs up to date.

Install

FreeRide isn't in the Codex plugin directory yet, and the Codex and ChatGPT apps have no button for adding a plugin from outside it. One command does it. Open Terminal and run:

curl -fsSL https://freeride.dev/install/codex.sh | sh

It finds Codex (the apps keep their own copy, which isn't on your PATH), installs FreeRide and opens your browser to sign in. Then restart Codex or the ChatGPT app.

On Windows, or to run each step yourself, use the Codex CLI:

codex plugin marketplace add freeride-dev/freeride
codex plugin add freeride@freeride
codex mcp login freeride

Sign in

The install command signs you in: approve in the browser window it opens. If that didn't happen, run the install command again, or codex mcp login freeride.

Set up a repo

Once per repo. Open the repo in Codex and type:

$freeride-setup

Or just ask: "Set up FreeRide for this project." If you forget, the agent offers once, the first time you mention the project or it logs work there.

Setup asks which project the repo belongs to, or creates a new one. It writes .freeride.json (the project's id, no secrets) and adds FreeRide's rules to AGENTS.md (read by Codex and Cursor) and CLAUDE.md (read by Claude Code). It shows every change and asks once. Commit the files, and teammates who pull the repo are set up too, in any coding app.

Allow the hooks. Codex asks once to approve the plugin's hooks (a "Review hooks" window). They're FreeRide's reminders, such as suggesting to log work after a build. FreeRide works without them, just with fewer reminders.

Codex has a smaller limit on how much a tool can return, so FreeRide sends it a shorter project briefing. The facts are the same; anything left out is one search away.

Updates

Run the install command again. It's safe to repeat, and brings FreeRide up to date. Most of FreeRide runs on our server, so most improvements reach you either way.

If something's off

  • "codex: command not found". The apps don't add codex to your terminal. Use the install command above, which finds it for you.
  • FreeRide isn't in the Codex extension for VS Code or other editors. The extension doesn't load plugins yet. Use the Codex app or CLI.
  • The agent doesn't seem to know about FreeRide. Ask it how FreeRide is set up for this repo. If it isn't, type $freeride-setup, then restart Codex.
  • Asked to sign in again. Run codex mcp login freeride.

More in Troubleshooting & FAQ →.