Quickstart

Get FreeRide working with your AI agent in a few minutes.

What you need

• An AI app: Claude Code, Codex or Cursor for building; Claude chat or Cowork for thinking things through. FreeRide works in all of them, with the same projects.
• A FreeRide account. You create it the first time you sign in.

1. Install the plugin

Claude Code

/plugin marketplace add freeride-dev/freeride
/plugin install freeride@freeride

Claude chat and Cowork (claude.ai)

Go to Customize → Plugins → Add → Add marketplace, enter freeride-dev/freeride, and install FreeRide. Plugins on your claude.ai account also appear in Claude Code.

Codex

codex plugin marketplace add freeride-dev/freeride

Then install FreeRide from Plugins in the Codex app (or /plugins in the CLI).

Cursor

Open Customize in the sidebar, find FreeRide and select Install. (Not listed yet? The plugin's README has the manual install.)

2. Sign in

The first time FreeRide connects, a browser window opens. Sign in (Google or email) and approve. Each app remembers it.

• Claude Code: if you're not asked, run /mcp, pick the FreeRide server and sign in.
• claude.ai: open the FreeRide plugin's Connectors tab and click Connect. Chat has no FreeRide until this is done.
• Codex: sign in when asked, or run codex mcp login freeride.
• Cursor: on the FreeRide plugin page, click Authenticate next to the freeride server.
• Claude Desktop: if your chats run on the Desktop app, connect FreeRide there too (Settings → Connectors).

3. Link your repo (coding agents)

Open your project in Claude Code and run:

/freeride:setup

In Codex or Cursor, ask the agent: "Set up FreeRide for this repo." You don't always have to ask: when you talk about a FreeRide project in a repo that isn't linked yet, the agent offers to link it.

Setup asks which project the repo belongs to, or creates a new one. It then:

• writes .freeride.json, a small file with the project's id. Commit it, so teammates are linked too;
• adds FreeRide's rules to both CLAUDE.md (read by Claude Code) and AGENTS.md (read by Codex and Cursor), so the repo is ready in every agent, whichever one you set it up in. The rules sit between <!-- freeride-start --> and <!-- freeride-end --> markers, once per file. Everything outside the markers stays as it is, and running setup again changes nothing else.

It shows you every change and asks once before making it. Chat needs no linking: you just name the project.

In Cursor, use Agent mode: Ask mode is read-only and blocks FreeRide's tools. Cursor also asks before each tool call; you can let FreeRide's tools run without asking.

Your first session

Start a conversation in the linked repo.

Your agent gets briefed. It calls start_session and receives the project's state: recent work, features, open ideas, past decisions. On a new project the briefing is short. It fills up as you work.

Work as you normally would. Code, plan, debug. FreeRide doesn't change how you work.

Try saying:

• "Let's track this as a feature called Authentication" — a new feature
• "Let's use OAuth instead of email and password" — a decision, with the reason
• "We should add rate limiting at some point" — an idea
• "What have we worked on so far?" — a search of the project history

After meaningful work, the agent logs it. Not every edit: real progress. If it doesn't, say "please log this work."

In chat, try "Catch me up on <project>" or "Save this idea to <project>".

The dashboard

Sign in at freeride.dev with the same account. You'll see everything your agents captured: features, progress, ideas, decisions, docs and session history. It's where you see where things stand and steer what comes next.

Updates

The plugin updates through your app's plugin system, and most of FreeRide runs on our server, so improvements reach you without you doing anything. In Claude Code, /plugin shows your plugins and their updates.

Already using the FreeRide CLI?

Repos set up with npx freeride init keep working exactly as before. You don't have to change anything.

To move a repo to the plugin, install the plugin and run /freeride:setup in that repo. Setup finds the old setup, backs up the files it touches, switches the old connection off, and keeps your CLAUDE.md block. It shows every change first and deletes nothing.

The CLI is still there for repos on the older setup:

npx freeride status   # check a repo's older setup
npx freeride update   # refresh an older setup's hooks and instructions

Don't run them in a repo that uses the plugin.

Troubleshooting

• The agent doesn't seem to know about FreeRide: run /freeride:status in Claude Code. In Codex or Cursor, ask the agent how FreeRide is set up for this repo.
• Claude chat doesn't use FreeRide: make sure FreeRide is connected on the plugin's Connectors tab on claude.ai.
• Chat says FreeRide "isn't responding": usually a stale sign-in. Reconnect FreeRide (in the Claude Desktop app if your chats run there).
• Asked to sign in again: sign-ins can expire. Sign in again the same way (/mcp in Claude Code).

More in Troubleshooting & FAQ →.

What's Next

• Apps & Agents → — how FreeRide works in each app, and in chat
• How It Works → — the session flow and what you can do
• Tools Reference → — the tools your agent uses