Customization

FreeRide installs local files in your project that you own and can modify. After freeride init, the behavior of your agent is shaped by these files — and you can tune them to match how you work.

CLAUDE.md

The .claude/CLAUDE.md file contains persistent workflow instructions your agent reads at the start of every session. FreeRide's instructions are wrapped in markers:

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

What you can customize:

Inside the markers — modify FreeRide's default instructions. Change what the agent logs, how aggressively it tracks, or what it considers "meaningful progress." These changes will be overwritten by freeride update.
Outside the markers — add your own project-specific instructions. These are preserved across updates. Add coding conventions, architectural rules, or any guidance specific to your project.

Hook Scripts

FreeRide installs lightweight shell scripts in .claude/hooks/ that nudge your agent at key moments. These aren't rules — they're awareness triggers that help the agent make better decisions about tracking.

The hooks:

Hook	When it fires	What it does
Pre-edit awareness	Before the first edit in a work stretch	Reminds the agent that FreeRide is connected and suggests loading feature context
Edit tracking nudge	After several code changes	Asks the agent to consider whether the work is worth logging — with examples of what to skip
Build/commit nudge	After a successful build or git commit	Suggests logging progress. Stronger signal for commits (user confirmed satisfaction), softer for builds
Session recovery	After context compaction	Reminds the agent to reload session context

What you can customize:

Nudge text — change what the hooks say to the agent. Make them more or less aggressive about tracking.
Thresholds — the edit tracking hook fires every 3rd edit by default. Change the modulo in the script to fire more or less often.
Add your own hooks — FreeRide's hooks coexist with any other hooks you've configured. Add project-specific hooks in .claude/settings.json.

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.

Examples:

"Don't start a session for this conversation" — skips the session bracket entirely
"Don't log this work" — applies to the current piece of work
"Skip iteration logging for the rest of the session" — broader override
"Don't capture that as an idea" — overrides a backlog item capture
"Stop nudging me about doc updates" — quiets the doc-health prompts

These are soft overrides — the agent applies them for the rest of the conversation, and the next session starts fresh.

For a harder switch, the /freeride-off slash command (Claude Code) disables FreeRide's MCP for the session entirely; /freeride-on re-enables it.

Updating

When FreeRide releases improvements to hooks or instructions:

bash

npx freeride update

This replaces hook scripts and the content between CLAUDE.md markers. Your customizations outside the markers and your own hooks are preserved.

A version file at .claude/.freeride-version tracks what's installed. The update command compares versions and only reinstalls when there's something new.

What You Can't Customize (Yet)

MCP server behavior — the tools themselves, session logic, and response payloads are server-side. These aren't local files.
Dashboard layout — the web interface isn't customizable yet.
Tracking thresholds on the server — what counts as "meaningful progress" for auto-logging is determined by the instruction text (which you can modify) and the agent's judgment.

Project-level settings and preferences are on the roadmap.

How It Works → — the workflow that hooks and instructions support
Tools Reference → — what the agent is calling at each nudge
Troubleshooting & FAQ → — when a hook or update behaves unexpectedly