The Claude Code plugin runs the installed gem through ruby
Status: accepted
The repository is a Claude Code plugin marketplace with one plugin, plugins/rails-ai-context. A plugin is a folder Claude Code copies and starts commands from; it cannot run Bundler or install a gem, and its .mcp.json and hooks are one command line for every platform.
Decision
- The plugin ships no copy of the gem. Its server entry is
ruby -e "load File.join(ENV.fetch('CLAUDE_PLUGIN_ROOT'), 'scripts', 'serve.rb')", a command line no plugin update changes, so oneallowedMcpServersentry admits it for good (and admits any plugin that ships the same line), and the script loads the installed gem's own binary withserve, as its RubyGems binstub would, at the versionscripts/gem_requirement.rbnames. The binary then does what a standalone install does: finds the app root from the folder Claude Code started in, and hands off to the app's bundled copy when the Gemfile has one. Where it cannot serve, the script says why on stderr in one line, naming the Ruby and the folder it ran in: no gem for that Ruby (naminggem install rails-ai-context), only an older one (naminggem update), a Ruby older than 3.1, a bundle Claude Code inherited frombundle execthat lacks the gem, the installed gem's own activation error or load failure, and, on a gem older than 5.38.0, several apps or none. It then answers the MCP handshake itself, with no tools and that line as the server's instructions, rather than exiting: Claude Code 2.1.308 skips a plugin server that failed to start in every new session for 15 minutes, keyed by its command line, which is the same in every folder, so one session outside a Rails app would turn the plugin off everywhere. From 5.38.0 the script setsRAILS_AI_CONTEXT_PLUGIN=1before it loads the binary, and the gem'sserverefuses the same way (CLI::Refusal) wherever it would have printed an error and exited: no app source, a static tier that cannot read the app, an error the command raised. Claude Code 2.1.310 asksserver/discoverfirst; the refusal answers it with method-not-found, after which a client sendsinitialize, the one handshake that carries the instructions on every protocol. Where the serve hands the app to its bundled copy, the plugin's process stays in front of that copy as a proxy (ADR-0012), so a copy older than 5.38.0 that exits still leaves a connected server that names why. A start that fails before the script runs still exits, and gets that skip. - The server is started as
rubywith arguments:rubyis an executable on every platform, while a gem's binstub is a batch file on Windows, which a client that starts servers without a shell cannot run. One plugin file has no way to say "only on Windows".-enames no script, so rbenv picks the Ruby by the session's folder, not the plugin's. The hook is the shell formruby -- "${CLAUDE_PLUGIN_ROOT}/scripts/session_start.rb"; exit 0: Claude Code substitutes the path before any shell sees it, the quotes hold its spaces, a Claude Code too old for the exec form still runs it, andexit 0keeps a folder whererubycannot start, or a Ruby too old to read the script, from showing a hook error at every session start. The--ends rbenv's search of ruby's arguments for a script, whose folder (the plugin's) would otherwise pick the Ruby in place of the session's folder; ruby reads it as the end of its options everywhere. - The plugin has no
version. Claude Code then versions it by commit, so a fix reaches users without a manifest bump that the release checklist would have to carry. What the server does is versioned by the gem it runs. - The gem requirement is the first release with everything both scripts call and every tool and parameter
rules.mdnames. The plugin ships frommainto users who may have only that release, so CI installs it from RubyGems and runs the scripts against it, and fails while RubyGems lacks it. A release that changes what the plugin relies on (a named tool or parameter, whatdoctoror the update notice says about the plugin) raises the requirement to itself in a commit after it is published, and a rename keeps the old name working, and in the rules, until that commit. - The six rules the context files open with come from a SessionStart hook on startup, clear and compact (a resumed session holds them already), since the plugin writes no context file. The hook activates the installed gem as the server does and asks its
CLI::AppRootfor the app, so it speaks exactly where the server serves one, and prints nothing where the server would refuse the root (no app source, asEntryBoot.app_present?judges), without a gem that meets the requirement, or where the app's bundled copy, which the server hands the app to, is older than it. It printsrules.mdunless Claude Code already loads the generator's rules for that session: the app'sCLAUDE.mdor.claude/rules/rails-mcp-tools.md, or itsAGENTS.mdwhereCLAUDE.mdimports it or noCLAUDE.md,.claude/CLAUDE.mdorCLAUDE.local.mdis on the way up from the start folder to just below the filesystem root, or one of those files on the way up that carries them (an engine's above its test/dummy app), the user's own memory left out (Claude Code's default Project instructions). An app found below the start folder does not count, since Claude Code reads its files only later. Nor does it print where the app turns the rules off:.rails-ai-context.yml, aliases included, or a configure block inconfig/application.rb, the environment's file or an initializer settinganti_hallucination_rulestofalseornil, the last such literal in load order winning over the file. The hook runs no app code, so only a literal that ends its statement counts, outside=beginblocks. Rule 3 leaves out therails_get_configsectionsskip_toolsturns off, from the YAML or a literal list, assigned or appended, as the generator writes it.rules.mdisToolGuideHelper's default rendering word for word, and a spec holds it there, checks every tool and parameter it names against the server's, and runs the hook against this checkout'sAppRoot, so a rename there fails here. In a folder of several apps the server is ADR-0012's router, and the hook prints the rules with a last line naming the apps and theappargument a call picks one by; on a gem older than 5.38.0 the server script says to start Claude Code in one of them, by their paths from there, and the hook's last line names therails-ai-context --app-path <app> tool <name>form, since--app-pathis not something a plugin entry can pass. The hook finds the user's own memory in the config folderClaudeCodeSettings.user_config_dirnames. ClaudeCodeSettingsis the one place that knows Claude Code's files, and it reads them per session, by the folder the session started in, as Claude Code 2.1.308 does. A session reads that folder's project settings, its own local settings and then its git root's, which win (on macOS and Linux, where the root is not the home folder, the repository is not bare, and the root, its.gitand its.claudebelong to the user; otherwise only the folder's own), the user's and managed settings (with their drop-ins), merged per plugin key; every.mcp.jsonfrom that folder up to the filesystem root, whose servers start in that folder; and the/mcptoggles and local servers.claude.jsonkeeps under the folder's git root. A linked worktree's git root is its repository: the main checkout, or a bare repository's own folder. Onlytrueturns a plugin on. A user, project or local settings file whoseenabledPluginsfails Claude Code's schema is dropped whole; a managed one loses only the entries that fail, and a managed file that is not a JSON object stops Claude Code from starting. OnlyenabledPlugins' shape is checked, though Claude Code drops a file for other schema errors too..claude.jsonmoves withCLAUDE_CONFIG_DIR, and an older.config.jsonin the config folder is read in its place where one is left. ACLAUDE_CONFIG_DIRin theenvblock of the managed settings, else of the user's, movessettings.jsonandplugins/once more but not.claude.json; a relative one, empty included, leaves each session reading its own folder's. Managed settings come from the managed file and its drop-ins, read as if all were in force, not from the Claude console's server-managed settings, an MDM profile or the Windows registry. The MCP policy keys keep a server from starting: a deployedmanaged-mcp.json, which starts its own servers alone, adeniedMcpServersentry by name, exact command or url pattern, an allowlist that admits it by none of those (a plugin's server only by its exact command, since its name holds colons an allowlist entry cannot), and the managed lock on user and project servers, which fails closed as Claude Code's does. The managed marketplace policy (strictKnownMarketplaces,blockedMarketplaces) keeps a plugin from loading; an entry form the gem does not know counts as no evidence.- The sessions that matter are those started where the plugin would serve this app, as
AppRootandEntryBootjudge: the app, the two folders above it, the folderdoctorruns in, and any folder.claude.jsonkeeps a project for. The plugin runs in one where it is enabled, installed for that session's project (a project or local install counts in its own project only, a plugin from a marketplace added by a local folder or file needs no install but needs that folder, and where Claude Code never ran, as on CI, there is nothing to install), not turned off in/mcpand not blocked by policy. doctorjudges the session started where the app's config lives, and checks Claude Code wherever the plugin is chosen, whatever AI tools were chosen and under CLI-only mode. Where Claude Code never ran, as on CI, what the plugin needs from the machine is a warning, so a STRICT run stays green. If the plugin runs there, Claude Code's MCP check passes without a.mcp.json, and with no AI tools chosen another tool's config counts only where it exists and is broken. If it runs only in another session,doctornames that folder, how to turn it on here, and any second servers there. Wheremanaged-mcp.jsonis deployed,doctorjudges Claude Code by it alone, by the server of the gem's it names for this app, what keeps that one off (a deny or/mcp), and whether it can start, as a.mcp.jsonentry is judged. If the plugin runs nowhere,doctornames why, in this order: aCLAUDE_CONFIG_DIRthat is empty or relative, wherever it is set, a managed settings file Claude Code cannot read, not installed (asking for an install at the scope that leaves a committed file alone, and with no source where Claude Code knows the marketplace), a local marketplace folder that is gone, blocked by the marketplace policy, blocked by the MCP policy (naming every deny entry that holds it off, or the allowlist entry that admits it without turning the others to matching by command), or its server turned off in/mcp. Where the app's committed settings turn the plugin on and local or managed settings turn it off for this user, it names the file that does. It never namesinitfor Claude Code's.mcp.jsonwhere the committed settings turn the plugin on, since the install leaves that file alone there andinitwould change nothing. Existing context files are still checked for staleness; only their absence passes.- A server of the gem's, under any name and in any command form, or an HTTP entry under its name, that a session running the plugin would also start is a warning naming the commands that remove it and the folders to run them in, since Claude Code matches duplicates by command and these never match the plugin's. An entry naming no app counts, since it starts in the session's folder, which resolves to this app, and so does one whose app path is
${CLAUDE_PROJECT_DIR:-...}or${PWD}, which Claude Code expands from its own environment; one naming another app, or an app pathdoctorcannot read, does not, so no fix removes another app's server. A.mcp.jsonentry is removed where the committed settings turn the plugin on, and turned off with/mcpwhere only one user's do, since the file is then the team's. Turning the plugin off is offered too only where it leaves each session one server: once per repository, for every id the plugin runs under, and never where managed settings turn it on. - The install generator and
initwrite no Claude Code server into.mcp.jsonwhere the app's committed settings turn the plugin on, and say why; so doesinitin a folder holding one app whose own committed settings turn it on, since the plugin serves that app from there; it still writes the app's own.mcp.jsonfor sessions started in the app, which do not read that folder's settings, and says so. In a folder of several apps whose own committed settings turn the plugin on it writes no Claude Code server either, since the plugin serves each app there (ADR-0012). Whether the committed plugin runs for this user is oneClaudeCodeSettings#servingverdict, whichinitanddoctorboth render.uninstallnames, before it suggests removing the gem the plugin runs,claude plugin disable <id> --scope localonce per repository whose sessions run the plugin, run in a session folder that enables it, and the uninstall of the one install that serves them, by that install's own scope and folder.
Consequences
The plugin ships from main on every commit, not from a release tag. It must keep working with the release its requirement names, which CI checks; a release that changes what the plugin relies on raises the requirement only once it is published. The server name rails-ai-context and the script paths are what users' Claude Code configs and permission rules hold on to; renaming either breaks them. The plugin serves the session target AppRoot.target gives for where Claude Code started: one app, or each app of a folder of several through ADR-0012's router. ClaudeCodeSettings models what Claude Code 2.1.308 does where its docs are silent, so a Claude Code release that changes it can make doctor's verdicts wrong until the model follows.
Alternatives not taken
rails-ai-context serveas the command: what the standalone generator writes, but it does not start on Windows.- A shell launcher that picks
bundle execor the bare binary: needs a shell on Windows too, and repeats the handoff the binary already makes. - The rules in the server's MCP instructions: every client would get them, including apps whose
CLAUDE.mdalready carries them, so they would load twice there. - The rules as a skill: loaded only when the model chooses to, and in a real edit session it went unused. The context files put the rules in every session, and the hook does the same.
- The hook rendering the rules from the installed gem: matches any version's wording, but loads the whole gem at every session start, about a second more, for what a version requirement already keeps in step.
- The hook finding the app itself: a second copy of
AppRoot's rules (home folders, dependency folders, symlinks, nested apps) that drifted from it in its first version. - The hook booting the app to read its settings: exact, but slow and able to run app code at every session start, for a switch nearly every app sets as a literal.