How RailsInsight Gives AI Agents Structural Understanding of Your Rails App
I’m building a tool called RailsInsight that solves a problem I kept running into with AI coding agents on our clients’ Rails applications at reinteractive. The agent would ask for context, I’d point it at the codebase, and it would burn through 60,000 tokens reading files before it could answer a basic question about model associations. I was interested in whether a Rails-aware indexer could fix this. It can.
RailsInsight is a Rails-aware MCP server that gives AI agents deep structural understanding of your application — models, associations, routes, schema, authentication, jobs, and 56 total file categories — without reading every file.
This article covers what RailsInsight does, why Rails convention over configuration makes this kind of tool possible, how it reduces token consumption when agents read code, and how its blast radius analysis helps agents write safer code. I’ll also compare it against Shopify’s RubyDex, which takes a different approach to the same general problem.
Rails Has No Equivalent to What Laravel Ships Out of the Box
Laravel 12 now ships with an official first-party MCP server called Laravel Boost. It provides over 15 specialised tools and auto-generates context files for AI agents. It includes on-demand Agent Skills per detected Composer package and exposes a 17,000-piece documentation API. Laravel’s official docs have a dedicated “AI Assisted Development” page. I noticed this when I was researching what other frameworks were doing.
Rails has nothing like this. The closest thing the Rails world had was rails-mcp-server, which provides partial Rails awareness but no structural graph intelligence, no blast radius analysis, and no convention enforcement. RailsInsight is the first tool that gives AI agents the same depth of Rails-specific understanding that Laravel developers now get from their framework by default.
This isn’t a criticism of the Rails core team. It’s a gap in the Rails community’s toolchain that we’re filling because we work with Rails applications every day and we need this tooling to exist.
Why Convention Over Configuration Makes This Possible
Generic code analysis tools treat Ruby files as plain text. They can’t parse has_many :through, before_action filters, Devise modules, Pundit policies, or Turbo Stream broadcasts. The reason for this is that these aren’t standard Ruby syntax — they’re Rails DSL conventions built on top of Ruby’s metaprogramming.
RailsInsight works because Rails follows convention over configuration. I built the tool around this principle. A file at app/models/user.rb is a model. A file at app/controllers/posts_controller.rb is a controller. The naming conventions are predictable enough that RailsInsight can classify every file in your project into one of 56 categories without reading a single byte of file content — pure path-based analysis.
The structural scanner runs as Layer 3 of a 6-layer pipeline. It classifies files using path patterns alone, and the entire scan completes in under 2 seconds even on large projects. This is the foundation that makes everything else possible.
Once files are classified, 19 specialised deep extractors parse the actual file content. As an example, the model extractor understands has_many, belongs_to, has_many :through, polymorphic associations, scopes with their query bodies, enums with their values, callbacks, delegations, and ActiveStorage attachments. It also handles Rails 7+ features like encrypts and normalizes, and Rails 7.2+ token generators. The controller extractor picks up actions, before/after/around filters, strong params, rescue handlers, and rate limiting. It detects the allow_unauthenticated_access macro from Rails 8’s native authentication too.
A generic tool like Tree-sitter can’t parse any of this. Tree-sitter understands Ruby syntax, but Rails DSL methods look like regular method calls to a syntax parser. has_many :posts is indistinguishable from any other method invocation unless you know the Rails conventions that give it meaning.
How RailsInsight Reduces Token Consumption
Every time an AI agent reads a file to understand your codebase, it consumes tokens. On a moderately sized Rails application with 200 models, 80 controllers, and hundreds of views, I’ve seen naive approaches consume hundreds of thousands of tokens before the agent has formed any understanding of the application’s structure.
RailsInsight avoids this by building an index and serving it through MCP tools. When an agent calls get_overview, it receives a complete project summary in roughly 500 tokens. That includes Rails and Ruby versions, database adapter, authentication strategy, key models, key controllers, frontend stack, and file counts. That’s enough for the agent to orient itself. It can then decide what to look at next.
When the agent needs detail on a specific model, get_model returns associations, validations, scopes with their query bodies, enums with their values, callbacks, public methods, and the matching database columns from schema.rb — all in a single tool call. The agent doesn’t need to read the model file, the schema file, and the routes file separately.
The get_full_index tool uses token-budgeted formatting. It accepts a token_budget parameter (default: 12,000 tokens) and returns the complete index trimmed to fit. It prioritises sections by architectural importance — versions and statistics first, then schema, then models and controllers, then views and components. If the full index won’t fit, it progressively trims lower-priority sections. Binary search finds the optimal cut point.
The relationship graph is where the real token savings come in. RailsInsight builds a directed weighted graph with 22 edge types. These include has_many, belongs_to, inherits, includes_concern, routes_to, convention_pair, tests, and 15 others. When an agent calls get_subgraph with a skill like authentication, it gets only the entities and relationships relevant to that domain. Not the entire codebase. Personalised PageRank ranks entities by importance within each skill domain.
Research from code-review-graph benchmarks shows that knowledge graph approaches achieve 6–49x token reduction compared to file-by-file reading. That’s on real commits across real repositories. A separate paper from CodeCompass (arXiv, February 2026) demonstrated 99.4% architectural coverage on hidden-dependency tasks when agents had access to a structural graph. Vanilla agents without one scored 76.2%. RailsInsight’s graph is specifically tuned for Rails. The 22 edge types map directly to Rails conventions that generic tools can’t see.
Blast Radius Analysis: How Agents Know What Else Might Break
One of the features I find most useful for AI agents writing code is blast radius analysis. When an agent is about to modify app/models/user.rb, it needs to know what else in the application depends on that model. Without this information, the agent might change a column name and break 12 controllers it didn’t know about.
RailsInsight’s get_blast_radius tool accepts a list of changed files — or auto-detects them from git diff — and returns every impacted entity classified by risk level: CRITICAL, HIGH, MEDIUM, or LOW.
The risk classification uses BFS traversal through the relationship graph combined with Rails-specific escalation rules. Distance 0 — the changed entity itself — is always CRITICAL. Auth-related entities at distance 1 are escalated to HIGH because security changes have outsized risk. Schema changes propagating to distance 1 are also CRITICAL. The reason for this is that column and table changes break all direct dependents. Strong associations like has_many, belongs_to, and inherits (edge weight ≥ 2.0) at distance 1 are classified as HIGH. Everything else falls into MEDIUM or LOW based on distance and edge strength.
There’s a companion tool called get_review_context that builds a token-budgeted summary of the blast radius result. It groups impacted entities by risk level and fills the response with structural summaries — “User — 5 associations, has_secure_password, 3 scopes” — until the token budget is reached. CRITICAL and HIGH entities get full summaries. LOW entities get compact three-field summaries. The agent gets exactly the right amount of context for a code review without wasting tokens on low-risk entities.
This is particularly useful for project managers and team leads who are evaluating whether AI coding agents are safe to deploy on production Rails codebases. Blast radius analysis gives the agent guardrails — it knows what’s at risk before it writes a single line of code.
Test Intelligence for Coverage Gaps
RailsInsight includes five test intelligence tools. I added these because agents consistently struggled with two things: knowing where tests were missing, and knowing what patterns to follow when writing new ones.
get_coverage_gaps cross-references SimpleCov output with RailsInsight’s structural data. It produces prioritised lists of files needing coverage, with per-method granularity. get_test_conventions detects the project’s testing patterns. Does it use request specs or controller specs? Are let declarations lazy or eager? What does the authentication test helper look like? It answers all of these. get_domain_clusters groups models into clusters that share associations and factories. This means multiple test-generation agents can work in parallel without conflicting.
get_factory_registry parses FactoryBot factory definitions and returns structured data about available traits, sequences, and associations. get_well_tested_examples returns the highest-quality existing spec files as pattern references — selected by structural complexity, not just line count.
For engineering managers overseeing AI-assisted test generation, these tools mean the agent follows your team’s existing conventions rather than inventing its own patterns.
How RailsInsight Compares to Shopify’s RubyDex
Shopify’s RubyDex is a high-performance Ruby indexer written in Rust. It uses proper AST parsing via Prism to build a semantic graph of Ruby code — classes, modules, methods, constants, and their relationships. It’s fast, it’s thorough on pure Ruby, and it exposes an MCP server with six tools: search_declarations, get_declaration, get_descendants, find_constant_references, get_file_declarations, and codebase_stats.
RubyDex is a Ruby language indexer. RailsInsight is a Rails application indexer. I want to be clear about this distinction because it matters.
RubyDex understands that User is a class that inherits from ApplicationRecord. It can find method definitions, constant references, and ancestry chains. What it can’t do is understand Rails conventions. It doesn’t know that has_many :posts creates a relationship between the User model and the Post model. It doesn’t know that this relationship corresponds to a user_id foreign key in the posts table. And it can’t tell you that changing the User model might break the PostsController because of a naming convention.
RubyDex’s AST parser sees has_many :posts as a method call with a symbol argument. RailsInsight’s model extractor sees it as a structural association that generates methods, creates a dependency, and should be represented as a weighted edge in the relationship graph.
There’s a caveat though — these tools aren’t competitors. They solve different problems at different levels of abstraction. RubyDex is the right tool if you need precise Ruby language intelligence: finding all references to a constant, walking class hierarchies, or resolving require paths across a large Ruby project. RailsInsight is the right tool if you need an AI agent to understand the architectural structure of a Rails application: which models are central, what changes will break what, and how the authentication system is wired together.
RubyDex has 6 MCP tools focused on code navigation. RailsInsight has 17. Those cover project overview, deep model and controller analysis, route maps, schema with model-to-table mapping, skill-scoped subgraphs, pattern search, blast radius analysis, review context, coverage gaps, test conventions, domain clusters, factory registries, and well-tested examples. I built each of these because I kept hitting situations where the agent needed that specific context.
A Rails project would benefit from both running simultaneously. RubyDex for precise Ruby-level queries. RailsInsight for Rails-level architectural intelligence.
What This Means for Teams Managing Rails Applications
If you’re a project manager, engineering manager, or CTO with Rails applications in production, I wanted to share three things worth knowing about RailsInsight.
The first is that your AI agents are currently flying blind on Rails-specific conventions. Generic code analysis tools — and even Ruby-specific tools like RubyDex — don’t understand the Rails DSL. They can’t see associations, callbacks, route mappings, authentication strategies, or the 50+ other Rails-specific patterns that define your application’s architecture. RailsInsight fills that gap.
The second is that blast radius analysis gives you a measurable safety net for AI-assisted code changes. Before an agent modifies any file, it can check what else depends on that file. The risk classification gives both the agent and your team a clear picture of what’s at stake. I’ve found this is the kind of guardrail that makes the difference between “we tried AI agents and they broke things” and “we use AI agents with structural safety checks.”
The third is that RailsInsight works with any MCP-compatible AI agent: Claude Code, Cursor, VS Code with the MCP extension, and any future tool that supports the Model Context Protocol. You’re not locked into a specific IDE or AI provider.
Getting Started
RailsInsight runs from your Rails project root with a single command:
npx @reinteractive/railsinsight
Add it to your Claude Code MCP configuration:
{
"mcpServers": {
"railsinsight": {
"command": "npx",
"args": ["@reinteractive/railsinsight"]
}
}
}
The indexer scans your project structure, extracts Rails conventions, and builds a relationship graph with PageRank rankings. It exposes everything through MCP tools. The whole process takes under 2 seconds. All 17 tools are available with no tier restrictions.
RailsInsight supports Rails 6.0 through 8.1+, covering Webpacker through import maps, Sprockets through Propshaft, Devise through native Rails 8 authentication, Sidekiq through Solid Queue, and the full Hotwire stack.
What’s Next
We’re actively working on co-change coupling from git history. This will surface hidden dependencies between files that always change together but share no explicit code relationship. I’m also working on pattern momentum detection, which would tell agents “this team is moving toward service objects and away from model callbacks” based on measured git history trends rather than static rules.
If you’re running Rails applications and using AI coding agents, I’d recommend giving RailsInsight a try. I’m interested in hearing what works and what doesn’t — be very aware that this is still early and there are edges we haven’t hit yet. You can open an issue on GitHub or reach out directly.
You may also like
Why Does Your AI Agent Forget What You Told It? (And How to Make It Remember?)
Ps. if you have any questions
Ask here