Troubleshooting & FAQ

Common Issues

Agent doesn't seem to know about FreeRide

Run npx freeride status in your project directory
Check that you're logged in and the token is valid
Verify .mcp.json exists in your project root
Restart your MCP client (Claude Code, Cursor, etc.) — it reads .mcp.json at startup

MCP server won't connect

Check your internet connection — FreeRide's MCP server runs remotely at mcp.freeride.dev
Run npx freeride status to verify auth state
If the token expired, run npx freeride login to re-authenticate

The CLI prints the URL to your terminal. Copy and paste it into your browser manually.

A previous login attempt didn't complete cleanly. Close any hanging processes on that port and try again.

Agent isn't logging progress automatically

FreeRide uses judgment about what's worth logging. CSS experiments, typo fixes, and minor tweaks aren't logged automatically. If you want something logged, just tell your agent: "Please log this work."

The hooks nudge the agent at natural moments (after several edits, after a build, after a git commit), but the agent makes the final decision about whether the work is meaningful enough to record.

My session ended unexpectedly

FreeRide detects abandoned sessions and auto-closes them with summaries built from whatever was logged. Your next start_session picks up the full history. Nothing is lost.

Tip: when you finish a session intentionally, say "end session" — the agent writes a richer narrative summary (the story of the conversation) than the auto-abandon rollup. The next session's continuity is better when you close explicitly.

Context was compacted mid-conversation

When your AI client compresses conversation history, the agent loses its FreeRide context. A hook automatically reminds it to call start_session again, which reloads the session and project state. If the agent was mid-work on a feature, it should also reload the feature context.

freeride update overwrote my CLAUDE.md changes

FreeRide only replaces content between  and  markers. Add your custom instructions outside these markers to preserve them across updates. If you modified content inside the markers, those changes will be overwritten — consider moving them outside the markers instead.

FAQ

Does FreeRide work with clients other than Claude Code?

FreeRide works with any MCP-compatible client. Claude Code is the primary supported client, but Cursor, VS Code with MCP extensions, and other MCP clients can connect using the .mcp.json configuration. The hooks and CLAUDE.md are Claude Code specific — other clients may need their own configuration.

Is my project data private?

Your project data is stored in a secure database with row-level security. Only you can access your data, scoped to your authenticated account. No project data is shared between users.

Can I use FreeRide on multiple projects?

Yes. Run npx freeride init in each project directory and select or create a different project for each. Each project has its own knowledge base, features, and history.

What counts as an "agent action" for the free tier?

Each MCP tool call counts as one action. start_session, complete_work, search, create — each is one action. The free tier includes 50 actions per week, which is typically enough for a handful of active coding sessions. Pro raises the cap to 1,000 actions per week.

Can I export my data?

Your data is queryable through the search tool and visible on the dashboard. Bulk export functionality is planned.

Does FreeRide work offline?

No. FreeRide's MCP server runs remotely, so an internet connection is required. The local hooks and CLAUDE.md work offline, but the agent won't be able to call FreeRide tools without connectivity.

Team features are on the roadmap — shared projects, team management, and collaborative workflows. Currently, FreeRide is designed for individual use. Stay tuned.

Quickstart → — initial setup walkthrough
Customization → — hook and instruction tuning
How It Works → — what FreeRide does during a session