Troubleshooting & FAQ

Common Issues

The agent doesn't seem to know about FreeRide

Is the repo linked? In Claude Code, run /freeride:status. It shows the linked project, which FreeRide connections Claude Code can see, and whether the rules are in CLAUDE.md. In Codex or Cursor, ask the agent how FreeRide is set up for this repo.
Not linked yet? Run /freeride:setup (or ask Codex or Cursor to "set up FreeRide for this repo").
Signed in? Run /mcp in Claude Code and check the FreeRide server. Sign in if it asks. In Cursor, the FreeRide plugin page shows whether the freeride server needs Authenticate.
Restart the app after setup, so it reconnects with the repo's project.

Claude chat doesn't use FreeRide

Is FreeRide connected? On claude.ai, open Customize → Plugins → FreeRide → Connectors and make sure FreeRide shows as connected. Installing the plugin doesn't connect it on its own.
Ask directly once: "Use FreeRide to list my projects." If Claude says it can't find FreeRide, the connection is the problem.
For it to happen without asking, add the one-line instruction from Apps & Agents → to your claude.ai settings.

Chat says FreeRide "isn't responding"

Usually it's a sign-in that went stale, not an outage. If the Claude Desktop app is connected, your claude.ai chats run their tools through it, using its own FreeRide sign-in. Open the Desktop app, go to Settings → Connectors → FreeRide, disconnect and connect again. Otherwise reconnect on the plugin's Connectors tab on claude.ai.

FreeRide's tools don't run in Cursor

Ask mode blocks them. Switch the chat to Agent mode.
Waiting for approval. Cursor asks before each tool call (Run / Skip). You can let FreeRide's tools run without asking.

Claude saves ideas to its own memory instead of FreeRide

Claude's built-in memory sometimes takes "remember this" for itself. Say "save it to FreeRide" once, accept FreeRide's offer to note in Claude's memory where that project lives, or add the one-line instruction to your claude.ai settings. Any of these makes it stick.

FreeRide appears twice in Claude Code

If you connected FreeRide on claude.ai, Claude Code picks up that connection too, next to the plugin's own. Run /freeride:setup: it offers a one-line setting that turns off the chat copy in Claude Code only (chat keeps working). Repos still on the older CLI setup can also show FreeRide twice once the plugin is installed; setup switches them over.

"Which project?"

If FreeRide can't tell which project you mean, it asks instead of guessing. In a coding agent, link the repo (/freeride:setup) so it always knows. In chat, name the project or pick it from the list.

The agent isn't logging progress automatically

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

The nudges remind the agent at natural moments (after several edits, after a successful build), but the agent makes the final call.

My session ended unexpectedly

FreeRide closes idle sessions on its own, with a summary built from whatever was logged. If the agent logs more work in the same conversation later, the session reopens. Your next start_session picks up the full history. Nothing is lost.

Tip: when you finish intentionally, say "end session". The agent writes a richer summary than the automatic one.

Context was compacted mid-conversation

When your AI app compresses the conversation, the agent loses its FreeRide context. A nudge reminds it to call start_session again, which picks the session back up.

Sign-ins can expire after long breaks. Sign in again the same way: /mcp in Claude Code, the plugin's Connectors tab on claude.ai (and Settings → Connectors in the Claude Desktop app), codex mcp login freeride in Codex, Authenticate on the plugin page in Cursor.

Older CLI setup

For repos set up with npx freeride init:

Check the setup: npx freeride status.
Login expired: npx freeride login.
Browser doesn't open during login: the CLI prints the URL; paste it into your browser.
"Port 54789 is in use" during login: a previous login didn't finish. Close the hanging process and try again.
freeride update overwrote my CLAUDE.md changes: it only replaces content between  and . Keep your own instructions outside the markers.

To move one of these repos to the plugin, install the plugin and run /freeride:setup there.

FAQ

Which apps does FreeRide work with?

Claude Code, Codex and Cursor for building; Claude chat and Cowork for thinking things through. ChatGPT is coming. All of them share the same projects. See Apps & Agents →.

Does FreeRide replace Claude's or ChatGPT's memory?

No, they do different jobs. Their memory remembers you: preferences, how you work. FreeRide holds your projects: features, ideas, decisions, docs, work history, shared across apps and with your team.

Is my project data private?

Your project data is stored in a secure database with row-level security. Only you, and members of a workspace you've put a project in, can access it. No project data is shared between users otherwise.

Can I use FreeRide on multiple projects?

Yes. Link each repo to its project with the setup. In chat, name whichever project you're talking about; one chat can cover several.

Is FreeRide free?

Yes, for individuals: unlimited projects and no weekly meter. A fair-use limit only stops automated abuse. Teams that share projects in a workspace pay per seat.

Can I export my data?

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

Does FreeRide work offline?

No. FreeRide runs on our server, so it needs an internet connection.

Yes — workspaces. Create one, invite your teammates by email, and every member (and their agent) sees every project in it. See Teams & Workspaces →.

Quickstart → — setup walkthrough
Apps & Agents → — how each app works
Customization → — rules, nudges and turning things off