FreeRide
← Back to docs

Quickstart

Get FreeRide connected to your AI agent in under 5 minutes.

Prerequisites

  • Node.js 18+ installed
  • Claude Code — FreeRide is optimized for Claude Code. The core MCP tools work with any compatible client, but the full experience is built for Claude Code today. Support for Cursor, VS Code, Windsurf, and other clients is coming
  • A project you're working on (any language, any framework)

Setup

1. Log in

In your terminal, run:

bash
npx freeride login

This opens your browser for Google sign-in. Authenticate, and the CLI stores your session locally. You only need to do this once — the session persists across terminal sessions and refreshes automatically.

2. Initialize your project

Navigate to your project directory and run:

bash
npx freeride init

This does four things:

  • Links a project — select an existing project or create a new one
  • Generates .mcp.json — the configuration file your MCP client uses to find FreeRide's server
  • Installs workflow hooks — lightweight scripts that nudge your agent about tracking at natural moments
  • Installs CLAUDE.md instructions — persistent workflow guidance your agent reads at session start

If you already have a .mcp.json (from Supabase, Context7, or another MCP server), FreeRide merges into it — your existing servers are preserved. Same with CLAUDE.md: FreeRide writes its content between <!-- freeride-start --> / <!-- freeride-end --> markers, and anything outside the markers stays intact. Both files are flexible — your existing setup is never overwritten.

3. Open your project and authenticate the MCP connection

Open your project folder in Claude Code. Then run /mcp — this opens the MCP panel where you'll see FreeRide listed. Click Authenticate (or follow the prompt) — a browser tab opens, you sign in with the same Google account you used for freeride login, and the auth token gets cached on the client. One-time setup; every subsequent session connects automatically.

That's it. You're set up.

Your First Session

When you start a conversation with your agent, FreeRide activates in the background. Here's what to expect:

The agent calls start_session automatically. It receives an orientation payload — your project's current state, recent progress, open ideas, feature status. If this is your first session, the payload is minimal. It fills up as you work.

Work as you normally would. Code, brainstorm, plan, debug. FreeRide doesn't change your workflow. It listens and captures.

Try saying something like:

  • "Let's track this as a feature called Authentication" — the agent creates a feature
  • "I'm thinking we should use OAuth instead of email/password" — the agent captures this as a decision
  • "Oh, we should also add rate limiting at some point" — the agent captures this as a backlog idea
  • "What have we worked on so far?" — the agent searches your project history

After meaningful work, the agent logs progress. Not every edit — significant implementations, architectural changes, features completed. You'll see this happen naturally. If the agent doesn't log on its own, you can always say "please log this work."

The Dashboard

Sign in to freeride.dev with the same Google account you used for freeride login.

Your dashboard shows everything your agents have captured: features, progress, ideas, decisions, documents, session history. This is your window into the project — you steer priorities and review progress here.

Updating

When FreeRide releases updates to hooks, instructions, or the workflow:

bash
npx freeride update

This updates the local hook scripts and CLAUDE.md content (between the <!-- freeride-start --> / <!-- freeride-end --> markers). Any instructions you've added outside the markers are preserved.

Verifying the Connection

If you're unsure whether FreeRide is connected:

bash
npx freeride status

This shows your auth state, token status, linked project, and configuration health. If something's wrong, this is the first place to check.

You can also ask your agent: "Is FreeRide connected?" — it will check whether the MCP server is available and responding.

Troubleshooting

Agent doesn't seem to know about FreeRide: Run npx freeride status in your project directory. Verify you're logged in, the token is valid, and .mcp.json exists. Restart your MCP client after running freeride init.

Browser doesn't open during login: The CLI prints the URL — copy and paste it into your browser manually.

Already have .mcp.json from another tool: FreeRide merges into existing configurations. Run freeride init and your other MCP servers will be preserved.

MCP connection asks to re-authenticate: Claude Code caches the FreeRide MCP auth token, but it can expire or get invalidated after extended idle periods. Run /mcp in Claude Code, find FreeRide in the list, and click Authenticate again — same browser OAuth flow as Step 3 of Setup above. The new token replaces the old one automatically.

CLI token expired: The CLI session (from npx freeride login) refreshes automatically. If the refresh token is revoked (rare), run npx freeride login again. (Note: this is separate from the MCP client token — see above.)

What's Next