RubyMate — Ruby & Rails for Visual Studio Code

A single, self-contained extension for Ruby and Ruby on Rails development. RubyMate provides code intelligence, debugging, testing, Rails navigation, template editing, and gem management out of the box — no separate language server required.

Navigation and completion are powered by a built-in parser and persistent indexer (Tree-sitter with a legacy fallback). One workspace pull writes symbols and references to .rubymate/index; navigation queries and later warm starts reuse that index instead of rescanning source files.

Features at a Glance

Getting Started

1. Install RubyMate from the VS Code Marketplace.

2. Open any Ruby or Rails project — RubyMate activates automatically and begins indexing.

3. (Optional) Install the gems that power formatting, debugging, and tests:

   gem install rubocop debug rspec
   

   Or add them to your Gemfile:

   group :development, :test do
     gem 'debug'     # Debugging (Ruby 3.0+)
     gem 'rubocop'   # Linting and formatting
     gem 'rspec'     # RSpec test support
   end
   

Core navigation and completion need no extra setup. The gems above are only required for the features that depend on them.

Requirements

• Ruby 2.7+ (auto-detected via rbenv, rvm, chruby, asdf, or mise)
• Bundler (ships with standard Ruby installations)
• Rails 6.0+ (optional, enables Rails-specific features)

Code Intelligence

• Go to Definition — jump to any class, method, module, or constant.
• Find All References — see every usage of a symbol across the project.
• Symbol Search — locate any symbol in the workspace.
• Hover Documentation — view signatures and documentation inline.
• Type Hierarchy — inspect inheritance chains, included modules, and subclasses.
• Call Hierarchy — trace incoming and outgoing method calls.

Detection covers direct calls, method chains, dynamic sends, symbols, hash keys, delegates, aliases, block parameters, instance and class variables, and ActiveRecord associations.

Semantic Autocompletion

Context-aware completion that resolves the cursor position before suggesting:

• Member completion (user., order.line_items&.) resolves the receiver's type and offers its full method resolution order, including inherited and mixin methods, filtered by reachable visibility.
• Bareword completion ranks in-scope locals, self methods, and Ruby keywords together.
• Constants, namespaces, and variables — Foo, Namespace::, @ivar, @@cvar — resolve from the project's semantic graph.
• Core and Rails knowledge — String, Array, ActiveRecord::Base, and friends resolve through a bundled knowledge base, preferring RBS/RBI signatures installed on your machine.
• Call-graph ranking orders suggestions by real usage in your codebase.
• Call snippets expand methods with required arguments into calls with tab stops.

Toggle with rubymate.completion.enabled.

Rails Integration

• Smart Navigation — jump between Models, Controllers, Views, Specs, and Migrations.
• Route Explorer — browse and search routes, then navigate straight to the definition.
• Generators — create models, controllers, migrations, and scaffolds from the palette.
• Rails Console — open an integrated rails console.
• Schema & Migrations — view the schema, jump to table definitions, run migrations, and roll back — all from the command palette.
• Concerns — navigate to included concerns.

Database Tools

• Show the database schema and jump to table definitions.
• Inspect table columns.
• Generate a migration from a model.
• Open a database console and run ad-hoc SQL queries.

Templates & Hotwire

ERB, Haml & Slim

• 50+ Rails helpers — completion for link_to, form_with, render, image_tag, and more.

• Path helpers from routes — user_path, edit_user_path, new_admin_user_path, and so on.

• Instance variables — completion for @user, @posts from controller context.

• I18n keys — translation completion for t('.key') from your locale files.

• Go to Definition for partials across every common render form:

  <%= render 'shared/header' %>
  <%= render partial: 'form', locals: { user: @user } %>
  <%= render @user %>          <%# → _user.html.erb %>
  <%= render @users %>         <%# → _user.html.erb (singularized) %>
  <%= render layout: 'admin' %>
  <%= render template: 'users/show' %>
  

• Custom & path helpers navigate to their definition (current_user, admin?, user_path).

Hotwire

• Stimulus — completion and go-to-definition for controllers, actions, targets, and values, plus hover documentation. Controller location is configurable via rubymate.hotwire.stimulusPath.
• Turbo — completion for Turbo Frames, Turbo Streams, and Turbo Drive attributes.

Toggle the whole stack with rubymate.hotwire.enabled.

Debugging

Powered by Ruby's official debug gem (rdbg):

• One-click debugging — press F5 to debug the current file.
• Breakpoints — line, conditional, and exception breakpoints.
• Variable inspection — locals, instance variables, and watch expressions.
• Step debugging — step through code with full call-stack visibility.
• Rails debugging — debug servers, console sessions, and Rake tasks.
• Test debugging — debug RSpec and Minitest examples with breakpoints.

Ready-made launch configurations are contributed for the current file, the Rails server, RSpec, and attaching to a remote debugger.

Testing

A native Test Explorer for RSpec and Minitest:

• Test tree — hierarchical view of every test in the project.
• Run & debug — individual examples, suites, or whole files.
• Live results — pass/fail indicators with execution times.
• Auto-discovery — detects and watches test files for changes.
• Gutter icons — run or debug directly from the editor.

Code Quality

• RuboCop integration — linting with auto-fix.
• Formatting — format the document or selection with RuboCop; enable format-on-save with rubymate.formatOnSave.
• Auto-insert end — closes Ruby blocks automatically (rubymate.autoInsertEnd).
• N+1 query detection — flags likely N+1 ActiveRecord patterns (rubymate.enableN1Detection).
• Dead-code detection — finds unused classes, methods, and constants.
• Snippets — 35+ Ruby and Rails snippets.

Gem Explorer

A dedicated sidebar for managing gems (shown when a Gemfile is present):

• Grouped gem tree from Gemfile.lock (Default, Development, Test, Transitive).
• Outdated detection with one click.
• Security audit via bundle audit.
• Per-gem actions — open on RubyGems.org, browse source locally, bundle update, or copy the name/version to the clipboard.
• Bundle commands — run bundle install and bundle update from the toolbar.
• Auto-refresh — watches Gemfile and Gemfile.lock.

Keyboard Shortcuts

Standard VS Code shortcuts provided by RubyMate:

RubyMate commands (Ruby files):

Rails and database commands are available from the command palette (Ctrl+Shift+P) under the Rails and Database categories, or from the Ruby icon in the status bar.

Configuration

RubyMate works with sensible defaults. Common settings:

{
  // Auto-format Ruby files on save with RuboCop
  "rubymate.formatOnSave": false,

  // Auto-insert the 'end' keyword for Ruby blocks
  "rubymate.autoInsertEnd": true,

  // Ruby executable on the workspace host (auto-detected by default)
  "rubymate.rubyPath": "ruby",

  // Render documentation comments in the normal Ruby editor
  "rubymate.readerMode.enabled": false,

  // Test framework: "rspec" | "minitest" | "auto"
  "rubymate.testFramework": "auto",

  // Enable Rails-specific features (auto-detected)
  "rubymate.enableRailsSupport": true,

  // N+1 query detection
  "rubymate.enableN1Detection": true,
  "rubymate.n1DetectionExcludePaths": [],

  // Semantic autocompletion
  "rubymate.completion.enabled": true,

  // Parser engine: "auto" | "tree-sitter" | "legacy"
  "rubymate.parser.engine": "auto",

  // Hotwire (Stimulus & Turbo) support
  "rubymate.hotwire.enabled": true,
  "rubymate.hotwire.stimulusPath": "app/javascript/controllers"
}

For team consistency, commit the relevant keys to .vscode/settings.json.

Reader Mode

Toggle documentation rendering with RubyMate: Toggle Reader Mode or the Ruby editor's book icon. It is disabled by default; a manual toggle applies to the current document until it closes. Full-line comment groups and =begin/=end blocks are styled without changing source text or layout. Any cursor or selection intersecting a block reveals the complete original block.

Rendered comments use 90% of the code font size, one tab of extra indentation, and a thick dark-gray vertical rail. Code edits and edits to other blocks preserve unchanged comment renderings; parsing still checks for changes that turn comments into Ruby strings or other syntax.

Decoration hovers render Markdown headings, emphasis, inline code, lists/examples, common RDoc, and YARD @param, @return, @raise, @example, and @see. HTML and command links are disabled. Inline comments, shebangs, encoding/magic comments, and tooling directives are excluded. Reader Mode works without a Ruby installation; parser failures leave plain source and report the reason in its status.

Ruby Interpreter Selection

RubyMate: Select Ruby Interpreter offers detected installations, manual entry, and automatic detection. Save to the active folder (default), workspace, or host user settings. Subsequent Ruby, Bundler, RubyGems, RuboCop, Rails, test, rake, debugger, completion, and agent executions use the selected interpreter. Existing terminals and processes must be restarted to change their Ruby.

The rubymate.rubyPath value is one executable, not a shell command. It supports executable names, absolute/relative paths, spaces, ~, ${workspaceFolder}, and ${env:NAME}. Relative paths use the owning workspace folder. Invalid explicit paths produce an actionable error and never trigger a silent fallback. Examples: /home/you/.rbenv/shims/ruby on WSL, /home/deploy/.asdf/shims/ruby on SSH, and C:\\Ruby33-x64\\bin\\ruby.exe on Windows.

Remote Development

RubyMate is a workspace extension: in WSL, Remote SSH, Dev Containers, and Codespaces it runs on the same host as your workspace and executes Ruby tools there.

• WSL / Remote SSH — open the folder through the corresponding Remote extension and enable RubyMate on that host.
• Ruby path — rubymate.rubyPath is resolved on the workspace host, not the UI machine.
• Virtual workspaces — unsupported, because RubyMate needs real Ruby tools and files.

Run RubyMate: Show Runtime Status to see the active host, resolved Ruby/Bundler/RuboCop/ Rails/rdbg tools, and parser/index health.

Troubleshooting

Extension not activating — confirm ruby -v works in the terminal and the project contains .rb files. Check View → Extensions → RubyMate for errors.

Navigation not working — first-time indexing takes a few seconds; save the file and, if needed, run "Developer: Reload Window".

Debugging issues — add gem 'debug' (Ruby 3.0+) and verify .vscode/launch.json.

Test Explorer empty — ensure RSpec or Minitest is installed and tests live under spec/ or test/; then refresh the Test Explorer.

Runtime Intelligence for AI Agents

RubyMate exposes an MCP stdio server for Kimi, Claude, Cursor, and other MCP-capable clients. Agents can execute saved workspace code instead of only predicting behavior from static analysis:

• rubymate_invoke calls a constant or instance method with JSON positional/keyword arguments, or evaluates an explicitly marked Ruby expression.
• rubymate_run_test runs an RSpec or Minitest file/example.
• rubymate_runtime_status reports trust, enablement, and Ruby tool availability.

Results include the observed value or exception, stdout/stderr, Ruby/Rails versions, duration, exit status, and optional TracePoint call/return/raise events with method owners and source locations. This supports dynamic dispatch such as define_method and method_missing. Line/block/C events and local values are opt-in; event counts, depth, strings, and output are bounded.

Connect a client

1. Open a trusted Ruby workspace in VS Code.
2. Run RubyMate: Configure Agent Runtime (MCP) and explicitly confirm enablement.
3. Paste the copied configuration into your client's MCP configuration and restart that client. The same mcpServers shape works in clients that support standard MCP stdio servers. Node.js 20+ must be on PATH.

{
  "mcpServers": {
    "rubymate": {
      "command": "node",
      "args": ["/absolute/path/to/extension/out/mcp/bridge.js", "--connection-file", "/absolute/path/to/agent-runtime-session.json"]
    }
  }
}

For Kimi use its MCP server settings, for Claude use its MCP configuration, and for Cursor use mcp.json. Consult the client version's documentation for the file location. RubyMate does not modify other clients' configuration files. Keep VS Code running; the bridge connects to the extension through an authenticated per-session Unix socket or Windows named pipe, not an HTTP port.

Example invocation arguments:

{
  "mode": "rails",
  "requires": ["app/services/pricing.rb"],
  "target": {
    "kind": "instance",
    "constant": "Pricing",
    "constructorArgs": [],
    "method": "total",
    "args": [2],
    "kwargs": { "currency": "USD" }
  },
  "trace": { "enabled": true, "events": ["call", "return", "raise"] }
}

Treat a response as evidence from one observed execution, not a guarantee that future executions will be identical. Each call uses a fresh Ruby process and saved files on disk; unsaved Ruby editors produce a warning. Rails defaults to RAILS_ENV=test with Spring disabled.

Execution safety and privacy

Execution is disabled by default, enabled per workspace, and also requires VS Code workspace trust. Code and tests can perform real database, network, filesystem, and job side effects. transaction: "rollback" requires Active Record and only rolls back participating database writes; it cannot undo other effects. Timeouts and cancellation terminate the execution process tree.

The per-session authentication token is stored only in a user-only connection file under VS Code global storage and is not placed in command arguments. Do not share that file. Traces and captured output may contain application data; captureLocals is off by default. Serializer redaction reduces accidental credential exposure but is not a substitute for reviewing sensitive results.

Settings: rubymate.agentRuntime.enabled, defaultTimeout, maxEvents, and traceIncludePatterns. Use RubyMate: Show Agent Runtime Status for diagnostics. Live attach/step-through of an already running server and persistent console sessions are not provided by these tools.

Contributing

Contributions are welcome:

• Report bugs: GitHub Issues
• Suggest features: GitHub Discussions
• Submit pull requests: see CONTRIBUTING.md

git clone https://github.com/Balaji2682/rubymate.git
cd rubymate
npm run install:all
cd extension && npm run compile   # then press F5 to launch the Extension Development Host

Resources

• Changelog — CHANGELOG.md
• Issues — GitHub Issues
• Discussions — GitHub Discussions
• Releases — Release Notes

Acknowledgments

RubyMate integrates with excellent Ruby tooling:

• Ruby Debug — the official debugger from the Ruby core team
• RuboCop — Ruby static analyzer and formatter

License

Released under the MIT License.