Rails Hyperdrive

Live introspection and stack-matched knowledge for AI coding agents, straight from your Rails app.

Rails Hyperdrive is a development-only Rails engine for working on Rails apps with AI coding agents. It gives the agent two things it can't get from source alone: live answers from the booted app, and guidance specific to the gems and versions in the bundle.

• Live introspection. The engine mounts an MCP (Model Context Protocol) server at http://localhost:3000/_hyperdrive/mcp with 8 tools that answer from the running app itself: eval Ruby, query the DB (read-only), tail logs, list models and routes, jump to source, look up docs, snapshot the stack. The agent asks the router instead of grepping routes.rb, and reads the live schema instead of replaying migrations.
• Stack-specific knowledge. bin/rails hyperdrive:init discovers skills, guidelines, agents, and commands shipped by companion gems and installs only the ones matching your Gemfile: guidance targeting Sidekiq, for example, lands only if your app bundles Sidekiq, at a version the guidance covers.

rails-hyperdrive is the mechanism; companion gems are the content. The gem itself ships no skills or guidelines, only the contract and the discovery/install engine. Content reaches your app three ways:

• Native support: the library gem itself ships a top-level skills/ directory in the skills.sh layout and opts in as a hyperdrive companion. The preferred route when the maintainer is on board: one gem, one source of truth.
• Adopted skill repos: an existing skills.sh skill repo packaged as a gem, content untouched, gating declared on the side.
• Dedicated companion gems: third-party guidance for a library that ships none itself.

On the last two routes, name the gem rails-hyperdrive-<name>: the prefix tells a Gemfile reader exactly what the gem is, though naming plays no part in discovery.

Rails Hyperdrive is built by Evil Martians, an American design and engineering consultancy for developer tools, AI, and cybersecurity startups.

---

Quick start

# 1. Add the dev gem
$ bundle add rails-hyperdrive --group=development

# 2. (Optional) Add a companion gem for your stack
$ bundle add rails-hyperdrive-sidekiq --group=development

# 3. Run the generator
$ bin/rails hyperdrive:init

  create  .mcp.json
  append  .gitignore
  append  Gemfile
  insert  config/routes.rb
  create  .hyperdrive/config.yml
  create  .claude/hyperdrive/guidelines/jobs-sidekiq.md
  create  .claude/skills/sidekiq-idempotency/SKILL.md
  create  .claude/hyperdrive/index.md
  create  CLAUDE.md
  create  .hyperdrive/lock.yml
   eager  1 guideline(s), ~240 tokens always in context

    done  hyperdrive initialized
  Mount: /_hyperdrive (in config/routes.rb)
  Server: 8 MCP tools at http://localhost:3000/_hyperdrive/mcp
  Installed 1 skill, 1 guideline, 0 agents, 0 commands

    rails-hyperdrive-sidekiq@1.2.0
      skill      sidekiq-idempotency
      guideline  jobs-sidekiq

  Next steps:
    1. bin/rails server
    2. Open Claude Code in this directory; it will read .mcp.json
    3. Verify the connection: curl -s http://localhost:3000/_hyperdrive/mcp ...

# 4. Start the dev server
$ bin/dev