rails-ai-bridge

Turn any Rails app into an AI-ready system — with real context, not guesswork.

One command. Zero config. Structured context + live introspection for AI assistants via compact project files and an MCP server.

---

What this gem does

AI coding tools are much better when they know your Rails app before they start editing. Without that context, they guess table names, miss routes, ignore conventions, and spend tokens rediscovering structure your app already has.

rails-ai-bridge turns a Rails app into an AI-readable project map:

• Static context files give assistants an immediate overview of your app, conventions, schema shape, routes, and important models.
• A read-only MCP server lets assistants ask for exact details only when needed, such as one model, one table, one controller, or one route group.
• Assistant-specific output keeps Claude Code, Cursor, Codex, Copilot, Devin, Gemini, and JSON consumers aligned without making you hand-write context files.

The goal is simple: help AI assistants produce code that fits your Rails app instead of generic Rails code.

Start here

Use the README as the shortest path to understanding and setup. Jump to deeper docs only when you need details.

You want to...	Read this first
Understand the idea in 3 minutes	How it works
Install and generate files	Quick start
Connect Claude Code or Cursor	Connect your AI client — Claude Code
Connect Devin	Connect your AI client — Devin and docs/devin-setup.md
Connect Copilot / Codex / Gemini	Connect your AI client
Check what the AI learns	What Your AI Learns
Choose :standard, :full, or opt-ins	Pick the right preset for your app
Use MCP safely	HTTP transport and mcp-security.md
Improve day-to-day AI results	Best Practices

When this helps

This is useful when you want an AI assistant to work inside a real Rails codebase, especially if the app has:

• More than a few models or routes
• Existing conventions that new code should follow
• Auth, background jobs, API endpoints, Hotwire, engines, or service objects
• A team that wants shared AI guidance committed to the repo
• Large schemas where dumping everything into context would be noisy

For tiny apps or one-off scripts, manual context may be enough. For team Rails apps, generated context plus MCP gives the assistant a much better starting point.

---

How it works

flowchart LR
  app[Rails_app]
  intro[Introspectors]
  files[Static_context_files]
  mcp[MCP_server]
  clients[AI_clients]
  app --> intro
  intro --> files
  intro --> mcp
  files --> clients
  mcp --> clients

1. Introspect: built-in scanners read your Rails app structure: schema, models, routes, controllers, gems, tests, conventions, and optional full-stack details.
2. Generate: rails ai:bridge writes compact, assistant-specific files such as AGENTS.md, CLAUDE.md, .cursor/rules/, and Copilot instructions.
3. Serve: rails ai:serve exposes read-only rails_* MCP tools so an assistant can drill into exact details on demand.

This creates two complementary layers:

Layer	What it does	Why it matters
Static files	Give the assistant passive project orientation at session start	Fewer cold starts and fewer generic assumptions
MCP tools	Return exact live details when requested	Less context bloat and fewer schema/route hallucinations

Compact files are ordered for usefulness: primary domain models, busy endpoints, recently migrated tables, and optional hot-table signals appear before lower-signal supporting details.

Safety model

• MCP tools are read-only. They inspect Rails structure; they do not write files or mutate the database.
• database_stats is opt-in because it queries PostgreSQL table statistics.
• Generated assistant context avoids credential values and suppresses secret-bearing config paths such as .env*, Rails credentials, master.key, private key material, and custom config/secrets or config/private files.
• HTTP MCP should stay bound to 127.0.0.1 unless you add authentication and network controls. See docs/mcp-security.md.

---

Quick start

From RubyGems (once published):

bundle add rails-ai-bridge
rails generate rails_ai_bridge:install

From GitHub (before or alongside RubyGems):

bundle add rails-ai-bridge --github=igmarin/rails-ai-bridge
rails generate rails_ai_bridge:install

Or add to your Gemfile:

gem "rails-ai-bridge", github: "igmarin/rails-ai-bridge"

Then bundle install and run the generator as above.

The install generator creates .mcp.json (MCP auto-discovery), sets up config/initializers/rails_ai_bridge.rb, and interactively guides you through generating your first bridge files.

Install profiles

The generator prompts you to pick a profile (or pass --profile to skip the prompt):

Profile	What it generates	Split rule dirs
custom (default)	Per-format prompts — pick exactly what you need	Yes
minimal	Claude, Cursor, Devin, Copilot, Gemini shims	No
full	Every format	Yes
mcp	Only .mcp.json — generate files later with rails ai:bridge	—

# Non-interactive — select profile upfront
rails generate rails_ai_bridge:install --profile=minimal

# CI/CD — skip file generation entirely
rails generate rails_ai_bridge:install --skip-context
rails ai:bridge   # generate later

Optional: gem install rails-ai-bridge installs the gem into your Ruby environment; you still add it to the app’s Gemfile for a Rails project.

Verify the integration in your Rails app

1. bundle install must finish cleanly — until it does, bundle exec rails -T and rails ai:serve (from .mcp.json) cannot be verified. Merging this gem to main does not fix a broken or incomplete bundle on the host app.
2. Regenerate in one shot — run rails ai:bridge (not only a single format) so route/controller summaries and relevance ordering stay consistent across CLAUDE.md, .cursor/rules/, and .github/instructions/.
3. Keep team-specific rules — generated files are snapshots. Use config/rails_ai_bridge/overrides.md for org-specific constraints (merged only after you delete the first-line <!-- rails-ai-bridge:omit-merge --> stub). Until then, the gem does not inject placeholder text into Copilot/Codex. See overrides.md.example for an outline. Alternatively re-merge into generated files after each rails ai:bridge (see .codex/README.md).
4. Tune list sizes — RailsAiBridge.configure { |c| c.copilot_compact_model_list_limit = 5 } (and codex_compact_model_list_limit); set 0 to list no model names and point only to MCP.
5. Check your readiness — rails ai:doctor prints a 0–100 score and flags anything missing after first install.

---

Why rails-ai-bridge over alternatives?

	rails-ai-bridge	rails-mcp-server	Manual context
Zero config	Yes — Railtie + install generator	No — per-project projects.yml	No
Token optimization	Yes — compact files + detail:"summary" workflow	Varies	No
Codex-oriented repo files	Yes — AGENTS.md, .codex/README.md	No	DIY
Live MCP tools	Yes — 13 read-only rails_* tools (extensible)	Yes	No
Auto-introspection	Yes — up to 27 domains (:full)	No — server points at projects you configure	DIY

Comparison reflects typical documented setups; verify against each project before treating any row as absolute.

---

What Gets Generated

rails ai:bridge generates assistant-specific files tailored to each AI workflow:

your-rails-app/
│
├── 🟣 Claude Code
│   ├── CLAUDE.md                                         ≤150 lines (compact)
│   └── .claude/rules/
│       ├── rails-context.md                              semantic layer (compact: capped per tier + MCP hint)
│       ├── rails-schema.md                               table listing
│       ├── rails-models.md                               model listing (includes semantic tier)
│       └── rails-mcp-tools.md                            full tool reference
│
├── 🟡 OpenAI Codex
│   ├── AGENTS.md                                         project instructions for Codex
│   └── .codex/
│       └── README.md                                     local Codex setup notes
│
├── 🟢 Cursor
│   ├── .cursorrules                                      legacy compat
│   └── .cursor/rules/
│       ├── rails-engineering.mdc                         alwaysApply: true (rules first)
│       ├── rails-project.mdc                             alwaysApply: true
│       ├── rails-models.mdc                              globs: app/models/**
│       ├── rails-controllers.mdc                         globs: app/controllers/**
│       └── rails-mcp-tools.mdc                           alwaysApply: true
│
├── 🔵 Devin
│   ├── .devinrules                                       ≤5,800 chars (6K limit)
│   └── .devin/rules/
│       ├── rails-context.md                              project overview
│       └── rails-mcp-tools.md                            tool reference
│
├── 🟠 GitHub Copilot
│   ├── .github/copilot-instructions.md                   ≤500 lines (compact)
│   └── .github/instructions/
│       ├── rails-models.instructions.md                  applyTo: app/models/**
│       ├── rails-controllers.instructions.md             applyTo: app/controllers/**
│       └── rails-mcp-tools.instructions.md               applyTo: **/*
│
├── 🔴 Gemini
│   └── GEMINI.md                                         directive briefing + MCP guide
│
├── 📋 .ai-context.json                                   full JSON (programmatic)
└── .mcp.json                                             MCP auto-discovery

Each file respects the AI tool's format and size limits. Commit these files so the same project guidance is available to your whole team.

Use rails ai:bridge:full to dump everything into the files (good for small apps <30 models).

---

What Your AI Learns

Category	What's introspected
Database	Every table, column, index, foreign key, and migration. Optional PostgreSQL stats add small / medium / large / hot table hints.
Models	Associations, validations, scopes, enums, callbacks, concerns, macros (has_secure_password, encrypts, normalizes, etc.), semantic tier (core_entity, pure_join, rich_join, supporting)
Non-AR Models	Ruby classes under the configured logical app/models path that aren't ActiveRecord, tagged as [POJO/Service] (included in :full, or opt in with :non_ar_models)
Routing	Every route with HTTP verbs, paths, controller actions, API namespaces, plus compact endpoint-focus summaries for busy controllers
Controllers	Actions, filters, strong params, concerns, API controllers; source metadata honors configured controller paths
Views	Layouts, templates, partials, helpers, template engines, view components
Frontend	Stimulus controllers, views, Turbo Frames/Streams, and broadcasts from configured Rails paths
Background	ActiveJob classes, mailers, Action Cable channels
Gems	70+ notable gems categorized (Devise = auth, Sidekiq = jobs, Pundit = authorization, etc.)
Auth	Devise modules, Pundit policies, CanCanCan, has_secure_password, Rails auth, CORS, CSP; source scans honor configured Rails paths
API	Serializers, GraphQL, versioning, rate limiting, API-only mode; source scans honor configured Rails paths
Testing	Framework, factories/fixtures, CI config, coverage, system tests
Config	Cache store, session store, middleware, initializers, timezone, CurrentAttributes from configured model paths
DevOps	Puma, Procfile, Docker, deployment tools, asset pipeline
Architecture	Service objects, STI, polymorphism, state machines, multi-tenancy, engines

The :full preset runs 27 introspectors. The :standard preset runs 9 core ones by default.

Start with :standard for most apps, then selectively enable additional introspectors (like :database_stats) as your use case requires. Use config.core_models to tell the generator which models are primary domain entities.

This keeps context focused and avoids unnecessary token usage while still allowing deep introspection when needed.

---

MCP Tools

The gem exposes 13 built-in tools via MCP that AI clients call on-demand (hosts can append more via config.additional_tools):

Tool	What it returns
rails_get_schema	Tables, columns, indexes, foreign keys
rails_get_model_details	Associations, validations, scopes, enums, callbacks, semantic tier, non-AR models (when enabled)
rails_get_routes	HTTP verbs, paths, controller actions
rails_get_controllers	Actions, filters, strong params, concerns
rails_get_config	Cache, session, timezone, middleware, initializers
rails_get_test_info	Test framework, factories, CI config, coverage
rails_get_gems	Notable gems categorized by function
rails_get_conventions	Architecture patterns, directory structure
rails_search_code	Ripgrep (or Ruby) search under Rails.root with allowlisted extensions, pattern size cap, and optional wall-clock timeout
rails_get_view	View layouts, templates, partials; optional per-file detail under the configured app/views path
rails_search_semantic	Semantic code search using rubydex — find declarations by name with types, locations, and relationships
rails_get_stimulus	Stimulus controllers: targets, values, actions, outlets (requires :stimulus introspector)
rails_list_registry	Skill pack catalog — list skills, agents, or active packs; requires config/rails_ai_bridge_registry.json

All tools are read-only — they never modify your application or database.

Smart Detail Levels

Schema, routes, models, and controllers tools support a detail parameter — critical for large apps:

Level	Returns	Default limit
summary	Names + counts	50
standard	Names + key details (default)	15
full	Everything (indexes, FKs, constraints)	5

# Start broad
rails_get_schema(detail: "summary")           # → all tables with column counts

# Drill into specifics
rails_get_schema(table: "users")              # → full detail for one table

# Paginate large schemas
rails_get_schema(detail: "summary", limit: 20, offset: 40)

# Filter routes by controller
rails_get_routes(controller: "users")

# Get one model's full details
rails_get_model_details(model: "User")

A safety net (max_tool_response_chars, default 120K) truncates oversized responses with hints to use filters.

Early real-world observations

Early project-level trials suggest the biggest improvement is not always dramatic token reduction by itself. In several runs, rails-ai-bridge led to faster, more focused responses even when total token usage only dropped modestly.

This is expected: compact assistant-specific files and the summary-first MCP workflow reduce orientation overhead, help the model navigate the codebase earlier, and improve the quality of the initial context.

Observed benefits so far:

• Less exploratory reading before the assistant reaches the relevant files
• Faster first useful response in Cursor and Devin trials
• Similar or slightly better answer quality with clearer project grounding
• More predictable drill-down via detail:"summary" first, then focused lookups

Results will vary by client, model, project size, and task type. More formal benchmarks are still in progress.

---

Connect your AI client

rails-ai-bridge gives every client two things: static context files loaded at session start (snapshots of your app), and live MCP tools called on-demand (always current). Both matter — files orient the assistant, tools answer specific questions without bloating context.

Client	Static files loaded automatically	MCP wiring
Claude Code	CLAUDE.md, .claude/rules/*.md	Auto — reads .mcp.json
Cursor	.cursorrules, .cursor/rules/*.mdc	Auto — reads .mcp.json
Devin	.devinrules, .devin/rules/*.md, AGENTS.md	Manual — create .devin/mcp.json
Copilot	.github/copilot-instructions.md, .github/instructions/	Not supported natively
Codex	AGENTS.md, .codex/README.md	Via .codex/mcp_servers.json
Gemini	GEMINI.md	Via Gemini CLI config

Claude Code

No MCP setup needed. Claude Code auto-detects .mcp.json at the project root and spawns bundle exec rails ai:serve automatically. Ask Claude "What rails_* MCP tools do you have?" to confirm — it should list rails_get_schema, rails_get_routes, and the rest.

If the connection fails: verify .mcp.json exists and that bundle exec rails ai:serve runs cleanly in your terminal.

Cursor

No MCP setup needed. Cursor auto-detects .mcp.json. If it does not pick it up, open Settings > MCP and add the server manually with BUNDLE_GEMFILE: "${workspaceFolder}/Gemfile" in the env block.

Ruby version manager issue (rbenv/rvm): Cursor may not inherit your shell environment when launching sub-processes. Fix: enable the HTTP transport instead.

# config/initializers/rails_ai_bridge.rb
RailsAiBridge.configure do |config|
  config.auto_mount = true
  config.http_path  = "/mcp"
  config.http_bind  = "127.0.0.1"
end

Start your Rails server and point Cursor to http://localhost:3000/mcp (type: SSE) in Settings > MCP.

Devin

Devin reads .devinrules, .devin/rules/*.md, and AGENTS.md automatically. MCP requires one manual step.

Step 1 — generate files:

rails ai:bridge    # all formats, including .devinrules and AGENTS.md

Step 2 — create .devin/mcp.json:

{
  "mcpServers": {
    "rails-ai-bridge": {
      "command": "bundle",
      "args": ["exec", "rails", "ai:serve"],
      "cwd": "/absolute/path/to/your/rails/app"
    }
  }
}

Use the absolute path in cwd — Devin does not inherit your terminal's working directory. Commit this file so your team gets the same setup.

Step 3 — verify: In a Devin session ask "What MCP tools do you have available?" — it should list the rails-ai-bridge server and all rails_* tools.

Ruby version manager issue: If bundle is not on PATH, use the absolute shim path (e.g. /Users/you/.rbenv/shims/bundle) or switch to the HTTP transport. See docs/devin-setup.md for the full guide including HTTP transport, skills, and troubleshooting.

GitHub Copilot

MCP is not natively supported in the Copilot VS Code extension. The static files (CLAUDE.md, .github/copilot-instructions.md, path-scoped .github/instructions/) give Copilot project grounding, and the MCP tools are documented in the generated files so Copilot knows what to ask — but it cannot call them automatically. For tasks that need live schema or route lookups, use Claude Code or Cursor.

Codex

Codex reads AGENTS.md at the repository root. MCP can be configured in .codex/mcp_servers.json. Run rails ai:bridge:codex to regenerate AGENTS.md and .codex/README.md (which includes Codex-specific setup notes).

HTTP transport (alternative for all clients)

If stdio MCP fails (usually a Ruby version manager PATH issue), start the HTTP server instead:

rails ai:serve_http   # http://127.0.0.1:6029/mcp

Or auto-mount inside your running Rails app:

RailsAiBridge.configure do |config|
  config.auto_mount = true
  config.http_mcp_token = ENV["RAILS_AI_BRIDGE_MCP_TOKEN"]   # required in production
  config.http_path  = "/mcp"
  config.http_bind  = "127.0.0.1"
end

Point your AI client to http://localhost:3000/mcp (or whichever port your Rails server uses) using transport type SSE. Keep the endpoint bound to localhost unless you add authentication. See docs/mcp-security.md for production hardening.

Claude Desktop (standalone app)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "rails-ai-bridge": {
      "command": "bundle",
      "args": ["exec", "rails", "ai:serve"],
      "env": { "BUNDLE_GEMFILE": "/absolute/path/to/your/rails/app/Gemfile" }
    }
  }
}

---

Best Practices

The shortest path to good results:

1. Commit generated static files so every teammate gets the same passive AI context.
2. Run MCP when doing real implementation work so assistants can drill into current schema, routes, models, controllers, and views.
3. Regenerate after meaningful app changes so static files do not drift from the code.
4. Start MCP calls with detail: "summary" and drill into one table, model, route group, or controller only when needed.
5. Put team-specific rules in config/rails_ai_bridge/overrides.md instead of hand-editing generated files.

Static files are snapshots. After a new model, migration, route change, significant refactor, or feature merge, run:

rails ai:bridge

For the full guide to client compatibility, token usage, overrides, staleness, and per-assistant workflow tips, read docs/BEST_PRACTICES.md.

Pick the right preset for your app

Preset	Introspectors	Best for
:standard (default)	9 core	Most apps — schema, models, routes, jobs, gems, conventions
:full	27	Full-stack apps where frontend, auth, API, and DevOps context matter

Add individual introspectors on top of a preset for targeted additions:

config.preset = :standard
config.introspectors += %i[non_ar_models views auth api]

For PostgreSQL apps where row-volume context matters, opt into safe approximate table-size hints:

config.introspectors += %i[database_stats]

This adds small, medium, large, or hot hints to generated context without exposing row data.

Check your readiness score

rails ai:doctor

Prints a 0–100 AI readiness score and flags anything missing: .mcp.json, generated context files, MCP token in production, and more. Run it after initial setup and after major configuration changes.

---

Configuration

# config/initializers/rails_ai_bridge.rb
RailsAiBridge.configure do |config|
  # Presets: :standard (9 introspectors, default) or :full (27). Add opt-in extras as needed.
  config.preset = :standard

  # Cherry-pick on top of a preset
  # config.introspectors += %i[non_ar_models views turbo auth api database_stats]

  # Context mode: :compact (≤150 lines, default) or :full (dump everything)
  # config.context_mode = :compact

  # Exclude models from introspection
  config.excluded_models += %w[AdminUser InternalAuditLog]

  # Tag primary domain models as core_entity (semantic context for AI + Claude rules)
  # config.core_models += %w[User Order Project]

  # Exclude paths from code search
  config.excluded_paths += %w[vendor/bundle]

  # Cache TTL for MCP tool responses (seconds)
  config.cache_ttl = 30
end

All configuration options

| Option | Default | Description | |--------|---------|-------------| | `preset` | `:standard` | Introspector preset (`:standard` or `:full`) | | `introspectors` | 9 core | Array of introspector symbols | | `context_mode` | `:compact` | `:compact` (≤150 lines) or `:full` (dump everything) | | `claude_max_lines` | `150` | Max lines for CLAUDE.md in compact mode | | `max_tool_response_chars` | `120_000` | Safety cap for MCP tool responses | | `excluded_models` | internal Rails models | Models to skip during introspection | | `core_models` | `[]` | Model names tagged as `core_entity` in introspection and `.claude/rules/` | | `excluded_paths` | `node_modules tmp log vendor .git` | Paths excluded from code search | | `auto_mount` | `false` | Auto-mount HTTP MCP endpoint | | `allow_auto_mount_in_production` | `false` | Allow `auto_mount` in production (requires MCP token) | | `http_mcp_token` | `nil` | Bearer token for HTTP MCP; `ENV["RAILS_AI_BRIDGE_MCP_TOKEN"]` overrides when set | | `search_code_allowed_file_types` | `[]` | Extra extensions allowed for `rails_search_code` `file_type` | | `search_code_pattern_max_bytes` | `2048` | Maximum `pattern` size (bytes) for `rails_search_code` | | `search_code_timeout_seconds` | `5.0` | Wall-clock limit per search (`0` disables); mitigates runaway regex / CPU | | `require_http_auth` | `false` | When `true`, HTTP MCP returns `401` if no Bearer/JWT/static auth is configured | | `rate_limit_max_requests` | `nil` (profile default) | Per-IP sliding window ceiling (`0` disables); not shared across workers | | `rate_limit_window_seconds` | `60` | Sliding window length for HTTP rate limiting | | `http_log_json` | `false` | One JSON log line per HTTP MCP response when enabled | | `expose_credentials_key_names` | `false` | Include `credentials_keys` in config introspection / `rails://config` | | `additional_introspectors` | `{}` | Optional custom introspector classes keyed by symbol | | `additional_tools` | `[]` | Optional MCP tool classes appended to the built-in toolset | | `additional_resources` | `{}` | Optional MCP resources merged with the built-in `rails://...` resources | | `http_path` | `"/mcp"` | HTTP endpoint path | | `http_port` | `6029` | HTTP server port | | `cache_ttl` | `30` | Cache TTL in seconds | | `watcher_formats` | `:all` | Formats regenerated by `rails ai:watch` (e.g. `%i[claude cursor]` to limit churn) | | `parallel_introspection` | `false` | Run introspectors concurrently (requires `concurrent-ruby`, which is already a Rails dependency) | | `parallel_pool_size` | `4` | Max threads in the parallel pool; capped at the number of active introspectors so no idle threads are created | | `parallel_timeout_seconds` | `10` | Per-introspector future timeout (seconds); timed-out introspectors return `{ error: "timed out after Ns" }` without blocking the others | | `registry.registry_manifest_path` | `"config/rails_ai_bridge_registry.json"` | Path to the registry manifest JSON file for skill pack resolution | | `registry.skill_cache_dir` | `"~/.rails-ai-bridge/cache"` | Directory for caching git repositories containing skill packs | | `registry.skill_packs` | `nil` | Explicit pack names to load, or `nil` for auto-detection based on framework | | `registry.local_registry_paths` | `[]` | Local directory paths (must contain `directory.json`) loaded at priority 0 | | `registry.resolver_ttl` | `1800` | Seconds to cache the wired resolver in memory; `0` disables caching | | `registry.git_pull_ttl` | `86400` | Seconds between `git pull` refreshes per cached pack (24 h default). Set to `0` to pull on every resolver rebuild | | `registry.git_timeout` | `30` | Seconds before a git operation (clone, pull, checkout) is forcibly interrupted | Other HTTP MCP knobs live only on the nested object, for example `RailsAiBridge.configuration.mcp.authorize`, `mcp.mode`, `mcp.security_profile`, and `mcp.require_auth_in_production` — see [docs/GUIDE.md](docs/GUIDE.md) and [docs/mcp-security.md](docs/mcp-security.md).

Extending the built-ins

If you need host-app or companion-gem extensions, register them explicitly in the initializer:

RailsAiBridge.configure do |config|
  config.additional_introspectors[:billing] = MyCompany::BillingIntrospector
  config.introspectors << :billing

  config.additional_tools << MyCompany::Tools::GetBillingContext

  config.additional_resources["rails://billing"] = {
    name: "Billing",
    description: "Billing-specific AI context",
    mime_type: "application/json",
    key: :billing
  }
end

Built-in MCP tools and resources now read through a shared runtime context provider, so tool calls and rails://... resource reads stay aligned to the same cached snapshot.

Rubydex Integration (Semantic Code Analysis)

Rubydex is Shopify's high-performance Ruby static analysis toolkit. rails-ai-bridge leverages rubydex out-of-the-box for semantic code understanding.

Setup:

Rubydex is installed automatically as a core dependency and is enabled by default.

To customize it in your initializer (config/initializers/rails_ai_bridge.rb):

   RailsAiBridge.configure do |config|
     # config.rubydex_enabled = false # Set to false to disable semantic analysis

     # Optional: enable the semantic introspector (adds :semantic to introspectors)
     config.semantic_introspector_enabled = true
     config.introspectors += %i[semantic]

     # Optional: control semantic context depth in generated files
     # config.semantic_context_depth = :standard  # :summary, :standard, or :full

     # Optional: incremental re-indexing (skip unchanged files on subsequent runs)
     # config.rubydex_incremental_threshold = 0.3  # full rebuild if >30% of files changed
     # config.rubydex_persist_index = true          # survive process restarts
   end

What you get:

Feature	Description
rails_search_semantic MCP tool	Fuzzy search for classes, modules, methods, and constants with type info and locations
Enhanced model introspection	Semantic summaries, similar model discovery, and complexity scores for each model
Semantic introspector	Codebase-wide pattern detection, inheritance analysis, and complexity hotspots
rails://semantic/analysis resource	Full semantic analysis accessible via MCP resource read
Context file enrichment	Semantic insights automatically included in generated AI context files
Incremental re-indexing	Only changed files are re-parsed on subsequent calls; unchanged files are skipped

Internal architecture: The RubydexAdapter wraps the rubydex API as a thin coordinator delegating to three single-responsibility collaborators: Serializer (hash conversion), Indexer (graph construction + source file scanning), and MethodCounter (flat method-counting pipeline). Incremental re-indexing is handled by the IncrementalIndexer service, which tracks file mtimes and triggers a full rebuild when the changed-file ratio exceeds rubydex_incremental_threshold. See CONTRIBUTING.md for the full project layout.

Configuration options:

Option	Default	Description
rubydex_enabled	true	Enable rubydex integration
rubydex_index_path	"tmp/rubydex_index"	Path for the rubydex index (must stay within Rails.root)
semantic_introspector_enabled	false	Enable the dedicated semantic introspector
semantic_context_depth	:standard	Depth of semantic context in generated files (:summary, :standard, :full)
rubydex_incremental_threshold	0.3	Fraction of changed files (0.0–1.0) above which a full rebuild replaces incremental patching
rubydex_persist_index	false	Persist the mtime snapshot to disk so incremental re-indexing survives process restarts

Performance considerations: Rubydex indexes your Ruby source files at startup. For large codebases, the initial indexing may take a few seconds. Subsequent calls re-use the in-memory index and only re-parse changed files, keeping re-indexing overhead proportional to churn rather than codebase size.

---

Skill Packs

rails-ai-bridge can load skill packs — shared collections of agent instructions — from versioned git repositories and surface them through rails_list_registry and rake tasks.

config.registry.registry_manifest_path = "config/rails_ai_bridge_registry.json"

Quick example manifest (config/rails_ai_bridge_registry.json):

{
  "version": "1.0.0",
  "packs": {
    "rails": { "source": "igmarin/rails-agent-skills" },
    "core":  { "source": "igmarin/ruby-core-skills", "always_loaded": true }
  },
  "default_stack": ["core"]
}

Pack sources accept local paths, HTTPS URLs (https://), SSH URLs (git@), or owner/repo GitHub shorthands. Plain http:// URLs are rejected. Packs can be pinned to a specific version with "ref": "v1.2.0".

To prevent network timeouts from blocking your server, set config.registry.git_timeout (default: 30 s). To control how often cached packs are refreshed, set config.registry.git_pull_ttl (default: 24 h; 0 to always pull).

See docs/skill-registry-guide.md for the full setup guide.

---

Stack Compatibility

Works with every Rails architecture — auto-detects what's relevant:

Setup	Coverage	Notes
Rails full-stack (ERB + Hotwire)	27/27	All introspectors relevant
Rails + Inertia.js (React/Vue)	~22/27	Views/Turbo partially useful, backend fully covered
Rails API + React/Next.js SPA	~20/27	Schema, models, routes, API, auth, jobs — all covered
Rails API + mobile app	~20/27	Same as SPA — backend introspection is identical
Rails engine (mountable gem)	~15/27	Core introspectors (schema, models, routes, gems) work

Frontend introspectors (views, Turbo, Stimulus, assets) degrade gracefully — they report nothing when those features aren't present.

---

Commands

Command	Description
rails ai:bridge	Generate all bridge files (skips unchanged)
rails ai:bridge:full	Generate all files in full mode (dumps everything)
rails ai:bridge:claude	Generate Claude Code files only
rails ai:bridge:codex	Generate Codex files only (AGENTS.md + .codex/README.md)
rails ai:bridge:cursor	Generate Cursor files only
rails ai:bridge:devin	Generate Devin files only
rails ai:bridge:copilot	Generate Copilot files only
rails ai:bridge:gemini	Generate Gemini files only
rails ai:serve	Start MCP server (stdio)
rails ai:serve_http	Start MCP server (HTTP)
rails ai:doctor	Run diagnostics and AI readiness score (0-100)
rails ai:watch	Auto-regenerate bridge files on code changes
rails ai:inspect	Print introspection summary to stdout
rails ai:skills:list	Print skill catalog from loaded skill packs
rails "ai:skills:resolve[pack,name]"	Resolve and print a skill's full content
rails ai:skills:clear_cache	Remove locally cached pack repositories

Bridge modes:

rails ai:bridge                               # compact (default) — all formats
rails ai:bridge:full                          # full dump — all formats
CONTEXT_MODE=full rails ai:bridge:claude      # full dump — Claude only
CONTEXT_MODE=full rails ai:bridge:cursor      # full dump — Cursor only

Overwrite confirmation:

CONFIRM=1 rails ai:bridge      # prompt before overwriting any changed file
rails ai:bridge                # silent overwrite (default)

You can also control this programmatically via RailsAiBridge.generate_context(on_conflict: :skip) — accepts :overwrite (default), :skip, :prompt, or a Proc (filepath) -> bool.

---

Works Without a Database

The gem parses db/schema.rb as text when no database is connected. Works in CI, Docker build stages, and Claude Code sessions without a running DB.

---

Requirements

• Ruby >= 3.2, Rails >= 7.1
• mcp gem (installed automatically)
• Optional: listen gem for watch mode, ripgrep for fast code search

---

vs. Other Ruby MCP Projects

Project	Approach	rails-ai-bridge
Official Ruby SDK	Low-level protocol library	We use this as our foundation
fast-mcp	Generic MCP framework	We're a product — zero-config Rails introspection
rails-mcp-server	Manual config (projects.yml)	We auto-discover everything

---

Documentation

The docs are layered so new users do not need to read everything at once.

If you need...	Start here
A quick install and mental model	This README
How to get better AI output day to day	docs/BEST_PRACTICES.md
Every command, config option, generated file, and MCP parameter	docs/GUIDE.md
Complete Devin setup — MCP wiring, skills, troubleshooting	docs/devin-setup.md
HTTP MCP hardening and production safety	docs/mcp-security.md and SECURITY.md
Skill packs: setup, sources, pinning, cache, troubleshooting	docs/skill-registry-guide.md
Skill registry technical reference	docs/registry-resolution.md
Offline mode design plan	docs/offline-mode.md
Gem improvement roadmap	docs/gem-general-improvements.md
Upgrade notes between major versions	UPGRADING.md
Release history	CHANGELOG.md
Development and contribution workflow	CONTRIBUTING.md

---

Contributing

git clone https://github.com/igmarin/rails-ai-bridge.git
cd rails-ai-bridge && bundle install
bundle exec rspec       # runs the full suite
bundle exec rubocop     # lint

See CONTRIBUTING.md for the full guide: adding introspectors, adding MCP tools, code style rules, PR process, and the maintainer release checklist.

For contributors, key folders include local guides:

• lib/rails_ai_bridge/README.md
• lib/rails_ai_bridge/introspectors/README.md
• lib/rails_ai_bridge/tools/README.md
• lib/rails_ai_bridge/serializers/README.md
• lib/generators/rails_ai_bridge/README.md
• spec/lib/rails_ai_bridge/README.md

Bug reports and pull requests: github.com/igmarin/rails-ai-bridge/issues

Acknowledgments & Origins

This gem ships as rails-ai-bridge (Ruby RailsAiBridge, version 3.1.0). Earlier iterations of the same codebase were distributed as rails-ai-context.

RailsMCP evolved from crisnahine/rails-ai-context, an excellent foundation for Rails MCP integration. This project extends that work with Codex support, smart token optimization, and a different long-term direction. All original commits and contributors are preserved in the git history.

License

MIT