One plugin server serves every app in the session

Status: accepted

A Claude Code session is often started in a folder that holds several Rails apps (work/shop, work/admin, a monorepo's apps/*). The plugin's server entry is one fixed command line (ADR-0011), and one process serves one app: the booted tier is one Rails app per process, and the gem keeps its configuration, tier and caches in process globals. Before this, such a session got a refusal with no tools, and the model fell back to guessing.

Decision

Consequences

Every app in the folder is reachable from one server, with no per-folder init and no turning the plugin off there. A folder whose committed settings turn the plugin on gets no workspace entries for Claude Code from init, as one app's folder gets none, and ClaudeCodeSettings counts a session there among those that run the plugin for each app.

The costs: the first call for an app waits for its boot (the typed boot limit, 60 seconds or RAILS_AI_CONTEXT_BOOT_TIMEOUT, then the static tier: no client waits on a child's handshake, so the router sets RAILS_AI_CONTEXT_ROUTED=1 for it), where a single-app session pays it before the handshake. Every app's server stays up until the session ends. Until an app's server has started, the list assumes the built-in tools its settings leave on, read without a boot, so its custom tools appear only after its first call, and a first call that used the built-in arguments where the app's copy takes others is told the name to call instead. A child whose Ruby is chosen another way than by a shim (rvm, chruby) runs the Ruby of the router's PATH. An app whose server keeps failing is started again at each call that names it.

Alternatives not taken