← Back to docs

Claude Code

Claude Code is where FreeRide does the most. In a repo that's set up, every conversation starts with a briefing on the project, and the agent logs what it builds and keeps the docs up to date.

Install

FreeRide isn't in Claude's plugin directory yet, so you add it by name. In Claude Code in your terminal, run:

/plugin marketplace add freeride-dev/freeride
/plugin install freeride@freeride
  • If Claude Code asks where to install it, pick Install for you (user scope). It then works in every repo.
  • When it says Installed FreeRide, run /reload-plugins (or restart Claude Code) to turn it on.
  • Turn on auto-update so FreeRide stays current: /plugin → Marketplaces → freeride → Enable auto-update. Claude Code leaves it off for plugins added this way.
  • If you get "/plugin isn't available in this environment", you're in a version of Claude Code that can't add plugins. Open a terminal, type claude, and run the two commands there.

Already added FreeRide on claude.ai with the same Claude account? Then it's in Claude Code too, and you can skip this.

Sign in

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

Not asked? Run /mcp, pick freeride and sign in.

Set up a repo

Once per repo. Open the repo in Claude Code, then type this in Claude Code, not your terminal:

/freeride:setup

From a terminal, that means cd your-repo, then claude to start Claude Code, then this command.

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. Then it:

  • writes .freeride.json, a small file with the project's id (no secrets);
  • adds FreeRide's rules to CLAUDE.md (read by Claude Code) and AGENTS.md (read by Codex and Cursor), between <!-- freeride-start --> and <!-- freeride-end --> markers. Everything outside the markers stays as it is.

It shows every change and asks once before making it. Commit the files, and teammates who pull the repo are set up too, in any coding app. Rather not put FreeRide's files in the repo? Each person can set up their own copy instead: see Setting up a shared repo →. Check the setup any time with /freeride:status.

Already have code? Run /freeride:bootstrap to build the FreeRide project from it. It reads the code first, shows you the areas it suggests, and waits for your OK before filling in docs, decisions and ideas.

Updates

Claude Code doesn't update plugins from outside Anthropic's directory unless you ask it to. Turn it on once: /plugin → Marketplaces → freeride → Enable auto-update. If you haven't, your agent mentions it when a newer FreeRide is out. To update by hand: /plugin → Marketplaces → freeride → Update, then /reload-plugins.

Most of FreeRide runs on our server, so most improvements reach you either way.

Moving from the FreeRide CLI

Repos set up with npx freeride init keep working as before. To move one 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.

Until then, the CLI still serves those repos (npx freeride status, npx freeride update). Don't run it in a repo that uses the plugin.

If something's off

  • The agent doesn't seem to know about FreeRide. Run /freeride:status. If the repo isn't set up, run /freeride:setup, then restart Claude Code.
  • FreeRide shows up twice. If you also connected FreeRide on claude.ai, Claude Code loads that connection too. Run /freeride:setup: it offers a one-line setting that turns off the chat copy in Claude Code only. Chat keeps working.
  • Claude Code on the web (claude.ai/code) doesn't load plugins yet, so FreeRide isn't there.
  • Asked to sign in again. Sign-ins can expire after a long break. Run /mcp and sign in.

More in Troubleshooting & FAQ →.