Customization

You can shape how your agent uses FreeRide: the rules it reads, the nudges it gets, and what it skips. Most of it is plain text you can edit.

The rules block

In a linked repo, FreeRide's rules live in your agents' instructions files. Setup writes them to both, so the repo works in every agent:

CLAUDE.md for Claude Code. If the rules are already in .claude/CLAUDE.md, or that's your only instructions file, they go there instead. Never in both: Claude Code reads both files.
AGENTS.md for Codex and Cursor.

Each file gets one block, between markers:

<!-- freeride-start -->
... FreeRide workflow rules ...
<!-- freeride-end -->

This short block is what keeps the agent using FreeRide in every conversation, including after its context gets compacted. Keep it.

What you can customize:

Outside the markers — add your own project instructions: coding conventions, architecture rules, anything. FreeRide never touches it.
Inside the markers — you can edit FreeRide's rules (what counts as meaningful progress, how eagerly to capture ideas). Running the setup again refreshes this block to the latest version, so keep your own rules outside the markers.

Chat instructions

Chat apps don't read CLAUDE.md or AGENTS.md. To make Claude chat use FreeRide reliably, add one line to claude.ai Settings → Instructions for Claude (ChatGPT has the same idea under Custom instructions):

For my projects, use FreeRide: catch up on the project before we discuss it, and save new ideas and decisions to FreeRide, not to your built-in memory.

If you keep a claude.ai Project per FreeRide project, you can also add "This is FreeRide project <name>" to that Project's instructions.

Nudges

The plugin includes a few lightweight hooks that nudge your agent at key moments in a linked repo. They're awareness, not rules: the agent still decides.

Nudge	When it fires	What it does
Session start	When a conversation starts	Tells the agent which FreeRide project the repo is linked to, and adds the rules if the repo's instructions file doesn't have them
Before the first edit	Before the agent starts changing code	Reminds it that FreeRide is connected and suggests loading the feature's context
After several edits	Every few untracked changes	Asks the agent to consider whether the work is worth logging
After a successful build	After a build, test or lint command succeeds with untracked changes	Suggests logging progress
After compaction	When the conversation's context is compacted	Reminds the agent to reload its session

Hooks run in Claude Code, Codex and Cursor. Codex asks you once to approve them. In Cursor, two arrive a step later because Cursor has no matching moment: the first-edit reminder comes right after the first edit, and the compaction reminder at the agent's next tool call. Chat apps don't run hooks.

Repos on the older CLI setup have these as local scripts in .claude/hooks/, which you can edit directly.

Tell the agent what to skip

Nothing in FreeRide is forced. The agent decides what to call, so if you tell it to skip something, it just doesn't do it.

"Don't start a session for this conversation" — skips the session entirely
"Don't log this work" — applies to the current piece of work
"Don't capture that as an idea" — overrides a capture
"Stop nudging me about doc updates" — quiets the doc prompts

These last for the conversation. The next one starts fresh.

Turning FreeRide off

For the rest of a conversation: just tell the agent.
In Claude Code: /mcp lets you turn off the FreeRide connection for the current repo. /plugin lets you disable the plugin entirely.
In other apps: disable the plugin or the FreeRide connector in the app's settings.
Older CLI setup: /freeride-off and /freeride-on still work in those repos.

Updating

The plugin updates through your app's plugin system, and most of FreeRide runs on our server, so improvements reach you without any action. To refresh a repo's rules block to the latest wording, run the setup again (/freeride:setup in Claude Code).

Repos on the older CLI setup update with npx freeride update, which replaces the hook scripts and the content between the markers. Don't run it in a repo that uses the plugin.

What you can't customize (yet)

The tools themselves — the tools, session logic and what they return run on FreeRide's server.
Dashboard layout — the web interface isn't customizable yet.

Project-level settings are on the roadmap.

How It Works → — the workflow the rules and nudges support
Apps & Agents → — what each app supports
Troubleshooting & FAQ → — when something behaves unexpectedly