rails-ai-context

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/crisnahine/rails-ai-context/main/docs/assets/logo-dark.svg"> <img src="https://raw.githubusercontent.com/crisnahine/rails-ai-context/main/docs/assets/logo-light.svg" alt="rails-ai-context: ground truth for your coding agent" width="480"> </picture> </p> <h3 align="center">Your coding agent guesses your Rails app. Let it ask.</h3> <p align="center"> <a href="docs/SETUP.md"><img src="https://img.shields.io/badge/works_with-555" alt="Works with"></a> <a href="docs/SETUP.md#claude-code"><img src="https://img.shields.io/badge/Claude_Code-D97757?logo=claudecode&logoColor=white" alt="Claude Code"></a> <a href="docs/SETUP.md#cursor"><img src="https://img.shields.io/badge/Cursor-000000?logo=cursor&logoColor=white" alt="Cursor"></a> <a href="docs/SETUP.md#github-copilot"><img src="https://img.shields.io/badge/GitHub_Copilot-000000?logo=githubcopilot&logoColor=white" alt="GitHub Copilot"></a> <a href="docs/SETUP.md#opencode"><img src="https://img.shields.io/badge/OpenCode-000000?logo=opencode&logoColor=white" alt="OpenCode"></a> <a href="docs/SETUP.md#codex-cli"><img src="https://img.shields.io/badge/Codex_CLI-000000?logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI%2BPHBhdGggZmlsbD0iI2ZmZiIgZD0iTTMgNS40IDQuNCA0bDggOC04IDhMMyAxOC42IDkuNiAxMnpNMTMgMThoOHYyaC04eiIvPjwvc3ZnPg%3D%3D" alt="Codex CLI"></a> <a href="docs/CLI.md"><img src="https://img.shields.io/badge/Any_terminal-4D4D4D?logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI%2BPHBhdGggZmlsbD0iI2ZmZiIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMyAzaDE4YTIgMiAwIDAgMSAyIDJ2MTRhMiAyIDAgMCAxLTIgMkgzYTIgMiAwIDAgMS0yLTJWNWEyIDIgMCAwIDEgMi0yem0wIDJ2MTRoMThWNXptMyAzLjRMNy40IDdsNSA1LTUgNUw2IDE1LjYgOS42IDEyek0xMyAxNWg1djJoLTV6Ii8%2BPC9zdmc%2B" alt="Any terminal"></a> </p> <p align="center"> <a href="https://rubygems.org/gems/rails-ai-context"><img src="https://img.shields.io/gem/v/rails-ai-context?color=b4132c&label=gem" alt="Gem version"></a> <a href="https://rubygems.org/gems/rails-ai-context"><img src="https://img.shields.io/gem/dt/rails-ai-context?color=b4132c&label=downloads" alt="Downloads"></a> <a href="https://github.com/crisnahine/rails-ai-context/actions/workflows/ci.yml"><img src="https://github.com/crisnahine/rails-ai-context/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI status"></a> <a href="docs/COMPATIBILITY.md"><img src="https://img.shields.io/badge/Ruby-3.1_to_4.0-b4132c" alt="Ruby 3.1 to 4.0"></a> <a href="docs/COMPATIBILITY.md"><img src="https://img.shields.io/badge/Rails-7.0_to_8.1-b4132c" alt="Rails 7.0 to 8.1"></a> <a href="LICENSE"><img src="https://img.shields.io/github/license/crisnahine/rails-ai-context?color=b4132c" alt="MIT license"></a> <a href="https://registry.modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP_Registry-listed-b4132c" alt="Listed in the MCP Registry"></a> </p> <p align="center"> <a href="https://crisnahine.github.io/rails-ai-context/">Website</a> · <a href="#try-it-in-your-rails-app">Quick start</a> · <a href="https://crisnahine.github.io/rails-ai-context/FAQ.html"><b>FAQ</b></a> · <a href="#what-it-does">What it does</a> · <a href="#a-closer-look">A closer look</a> · <a href="#how-it-works">How it works</a> · <a href="docs/TOOLS.md">Tools reference</a> · <a href="CONTRIBUTING.md">Contributing</a> </p> <p align="center"> <a href="https://crisnahine.github.io/rails-ai-context/FAQ.html"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/crisnahine/rails-ai-context/main/docs/assets/faq-dark.svg"><img src="https://raw.githubusercontent.com/crisnahine/rails-ai-context/main/docs/assets/faq-light.svg" alt="Questions before you install? Read the FAQ. Do I need MCP support in my AI tool? No. The gem works three ways. 1, MCP server: AI calls tools via the protocol, the best experience. 2, Static files: generated context files (CLAUDE.md, .cursor/rules/, etc.). 3, CLI: the same 35 tools from the terminal, no server needed. More questions the FAQ answers: What does this gem do? Which AI tools are supported? Is this safe for production? Does it work without a database? Do I need to commit the generated files? How does this compare to a hand-written CLAUDE.md?" width="860"></picture></a> </p> <br> <p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/crisnahine/rails-ai-context/main/docs/assets/session-dark.svg"> <img src="https://raw.githubusercontent.com/crisnahine/rails-ai-context/main/docs/assets/session-light.svg" alt="One session with rails-ai-context, each line from a real answer recorded against the sample app in this repository. It asks about a table: the users table's role column is an integer, not null, default 0, and index_users_on_email is unique. Before it calls an association: User has_many articles, dependent destroy, foreign key author_id. Before it writes an action: the before filter authenticate_user! comes from ApplicationController and is skipped on index and show. Before it writes a test: rspec, factories in spec/factories, 3 files, with the traits in_review and published. It traces a method: 4 call sites, among them article_publisher.rb, a service, with the line return false unless @article.publishable?. When the app cannot boot: a STATIC line says the answer serves static analysis and runtime-only data is marked UNAVAILABLE. Over MCP in Claude Code, Cursor, GitHub Copilot, OpenCode and Codex CLI, or as rails-ai-context tool NAME in any terminal." width="860"> </picture> </p>

Contents

• What it does
• Try it in your Rails app
• A closer look: the schema, the model, the inherited filters, the trace, the app that cannot boot, the six rules
• The tools
• How it works
• What it costs
• Questions you should ask first
• What it will not do
• Install options and configuration
• Troubleshooting
• Development
• Contributing and security
• Learn more

What it does

An assistant writing Rails code knows what an average Rails app looks like. Yours has its own columns, associations, filters and test setup, and the assistant starts every session with none of that. It writes a migration for a column that exists, calls user.posts when the association is user.articles, scaffolds FactoryBot into a fixture suite, and misses the before_action a parent controller adds. You catch it, fix it, re-prompt, and something next to it breaks.

rails-ai-context gives the assistant 35 tools that read the app itself, over MCP from the AI tool or from the command line. Every answer is read from the app and says how sure it is, and most end with a hint for the next call.

| When | What the assistant gets | A real line from an answer | |---|---|---| | It asks about a table | Columns with types, nulls and defaults, the indexes, the model on the table | index_users_on_email on (email) (unique) | | Before it calls an association | Associations with their options, validations including the implicit ones, enums, scopes, callbacks, concerns | has_many articles dependent: destroy (foreign_key: :author_id, inverse_of: :author) | | Before it writes an action | The actions, every filter with where it was inherited from, strong parameters, the layout | before authenticate_user! (from ApplicationController) (skipped on: index, show) | | Before it writes a test | The framework, where the factories or fixtures live, their traits, a template in the app's style | Factories: spec/factories (3 files) | | It traces a method | The definition and source, what it calls, every caller grouped by file and kind, the tests | app/services/article_publisher.rb (Service) · 11: return false unless @article.publishable? | | When the app cannot boot | The same tools, from config/routes.rb, the schema dump and the source, saying so | [STATIC] Static mode (static mode requested with --no-boot). Serving static analysis; runtime-only data is marked [UNAVAILABLE]. |

Each line comes from the sample app in this repository, a blog with Devise, an admin namespace, a JSON API, a Sidekiq job and a FactoryBot suite. The website records the whole answers every time it is built, by running the gem at that commit: crisnahine.github.io/rails-ai-context.

The install writes the files each AI tool reads, so the assistant knows the tools exist and how to ask: the MCP config, one root context file with six anti-hallucination rules, and rules that load when a model, a controller or a migration is open. The tools are read-only, the SQL tool runs inside a read-only transaction, and files that hold secrets are never served.

Try it in your Rails app

Open your AI tool at the root of your Rails app and paste this. It installs the gem, sets up the AI tool you are in, checks the result and tells you the one step left.

<!-- BEGIN install-prompt: kept identical to "Install (recommended)" in docs/PROMPTS.md by spec -->

Install the rails-ai-context gem in this Rails app so you can read its schema, models, routes and code through its tools instead of guessing.

1. Run `ruby -v` and `bundle exec rails -v`. rails-ai-context needs Ruby 3.1+ and Rails 7.0+. If either is older, stop and tell me.
2. Pick TOOL, the key for the AI tool you are: claude (Claude Code), cursor (Cursor), copilot (GitHub Copilot in VS Code), opencode (OpenCode), codex (Codex CLI). If you are another AI tool, stop and tell me to use the "Another MCP client" prompt instead.
3. Run `bundle add rails-ai-context --group development --version '>= 5.35.0'`. If the Gemfile already lists it, run `bundle update rails-ai-context --conservative` instead. Then run `bundle exec rails-ai-context version`: it must print 5.35.0 or newer, the first version with the flags used below. If it is older, the Gemfile pins it: change its rails-ai-context line to `gem "rails-ai-context", ">= 5.35.0", group: :development` and run `bundle update rails-ai-context --conservative`. If Bundler refuses (a frozen or deployment bundle), run `gem install rails-ai-context -v '>= 5.35.0'` instead and use `rails-ai-context init --tools TOOL --defaults` in step 4.
4. Run `bundle exec rails generate rails_ai_context:install --tools TOOL --defaults`. If it fails because the app can't boot, run `bundle exec rails-ai-context init --tools TOOL --defaults` instead; that one reads the source files when the app won't start.
5. Run `bundle exec rails-ai-context tool onboard` (or `rails-ai-context tool onboard` if you used gem install) and check it describes this app.
6. Tell me which files changed, then the "Next step" lines the install printed for TOOL, word for word. I have to do that step before your rails-ai-context MCP tools appear.

<!-- END install-prompt -->

Rather type it yourself? In the Gemfile:

bundle add rails-ai-context --group development
bin/rails generate rails_ai_context:install --tools claude --defaults

Standalone, with no Gemfile change:

gem install rails-ai-context
rails-ai-context init --tools claude --defaults

As a Claude Code plugin, which adds the MCP server and gives each session the six rules, and writes no context files. It runs the installed gem, so install that first, and run it in the app's folder:

gem install rails-ai-context
claude plugin install rails-ai-context --marketpla