thinkrail — one plugin, three CLI coding agents

ThinkRail's spec graph and workflow family, packaged so Claude Code, Codex CLI and the Grok CLI all load it from one directory:

• seven spec_* tools over an MCP stdio server — spec_grep, spec_get, spec_graph, spec_create, spec_update, spec_delete, spec_validate;

• ten workflow skills — choosing-a-workflow and the family it routes;

• the standing rule — specs are the ground truth, and every new piece of work enters the router.

It is a port: the spec-graph code and the workflow skill texts come from JetBrains ThinkRail (packages/spec-graph, packages/pi-thinkrail-workflow, Apache-2.0 / MIT — see NOTICE), through the DSH (dshthinkrailspec), PI-Desktop (pideskthinkrails) and omp (ompthinkrail) carriers. What changed here is the carrier, not the workflow: see architecture.md and the difference table below.

Install

The plugin is this directory. One command wires all three hosts (it is convergent — a second run leaves the same state):

node scripts/install.mjs            # add the plugin to claude, codex and grok; write the grok rule
node scripts/install.mjs --dry-run  # print what it would run
node scripts/install.mjs --uninstall

What it does per host, and why:

Manual equivalents, if you prefer to run them yourself:

claude plugin marketplace add "$PWD" && claude plugin install thinkrail@thinkrail
codex  plugin marketplace add "$PWD" && codex plugin add thinkrail@thinkrail
codex  mcp add thinkrail -- node "$PWD/mcp/server.mjs"
grok   plugin install "$PWD" --trust && grok plugin enable thinkrail

Restart the host (or reload plugins) so a new session picks everything up. In Claude Code, claude plugin details thinkrail prints the component inventory; Codex needs /hooks once to trust the hook; Grok's grok plugin details thinkrail and grok mcp doctor thinkrail show the same thing.

Edits to this directory reach the hosts differently: Claude Code loads the plugin in place and Grok links it, so both pick up a skill or tool change at the next session; Codex copies the plugin into ~/.codex/plugins/cache/, so re-run node scripts/install.mjs after editing.

The MCP server takes the workspace root from --root, then THINKRAIL_ROOT, then CLAUDE_PROJECT_DIR, then its own working directory (which every one of the three hosts sets to the session's project directory). A root that is missing or not a directory is reported as an error instead of as an empty project.

Related MCP server: MCP SDD Server

What loads

• Tools. One MCP stdio server (mcp/server.mjs) exposes the seven tools with the family's names, parameters and wording. The host namespaces them: mcp__plugin_thinkrail_thinkrail__spec_get on Claude Code, mcp__thinkrail__spec_get on Codex, thinkrail__spec_get on Grok.

• Skills. skills/<name>/SKILL.md — Claude Code registers them as thinkrail:<name> (invoke /thinkrail:spec-graph), Codex lists them as thinkrail:<name> (invoke $spec-graph), Grok lists them by name. Descriptions are kept under 150 characters because Grok cuts a longer catalog entry at ~150; everything else is the family's text, verbatim.

• The rule. hooks/workflow-rule.mjs holds the text; hooks/session-start.mjs hands it to SessionStart as hookSpecificOutput.additionalContext, which is model-visible developer context on Claude Code and Codex. Grok records a SessionStart hook's output without injecting it, so the installer writes the same text to $GROK_HOME/rules/thinkrail-workflow.md, a rules directory Grok scans in every project.

Anatomy

.mcp.json                the MCP server, on the path all three hosts read by default
hooks/                   the standing rule (text) and its SessionStart hook
mcp/server.mjs           JSON-RPC 2.0 over stdio; root resolution; error folding
mcp/tools.mjs            the seven spec_* tools: names, parameters, wording, scaffold headings
core/                    the host-free spec model (parse, graph, query, validate, store) + vendored yaml
skills/<name>/SKILL.md   the ten workflow skills
.claude-plugin/          Claude Code plugin + marketplace manifests
.codex-plugin/           Codex plugin manifest
.agents/plugins/         Codex marketplace index
.grok-plugin/            Grok marketplace index
plugin.json              Grok's optional manifest
scripts/install.mjs      the per-host wiring above
tests/                   node --test: core model, MCP transport, repo/host contract

Deliberate carrier differences

Behavior is ported, the carrier is not. Against pideskthinkrails (and, through it, dshthinkrailspec):

Everything else is byte-parity: tool names, parameter schemas, acceptance criteria, model-visible text, frontmatter dialect (a file is a spec exactly when its frontmatter carries non-empty id and type), lossless frontmatter edits, index revalidation, walk order, and the ten skill bodies.

Verified against

Each host was exercised with the real CLI on this machine; claude = Claude Code 2.1.284, codex = Codex CLI 0.153.4, grok = Grok 1.0.44.

Codex and Grok could not complete a model turn on this machine (no reachable credentials), so their per-host evidence stops at what the host records before the model call: plugin inventory, skill catalog, hook injection, MCP handshake and tool discovery. The rule text and the tool results themselves are verified live on Claude Code (which injected the rule and where the server answers), and over the MCP transport directly.

Known limits

• Codex cannot use ${CLAUDE_PLUGIN_ROOT} in MCP arguments. Verified: the variable is absent from a plugin MCP server's environment and a literal ${…} argument never resolves. That is why Codex's server is registered by absolute path in ~/.codex/config.toml, where it takes precedence over the plugin's own entry and inherits the session's working directory. Re-run scripts/install.mjs if the repository moves.

• Codex trusts hooks by hash. Until you run Codex's /hooks review, the SessionStart rule does not fire (the plugin's MCP tools still work).

• Grok has no session-start context channel, and its SessionStart hook output is recorded but not injected — hence the rules file. Grok also gates a server whose command lives inside the folder you are working in behind folder trust (--trust), which only matters when you run Grok inside this repository.

• Claude Code's plugin install of a local directory is live, not a frozen copy: the marketplace points at this directory and ${CLAUDE_PLUGIN_ROOT} resolves to it. Moving the directory means re-adding the marketplace.

• Rule 14 (verify-by-use) stays suspended. No request has been observed flowing router → worker → handoff in a real model turn; the tests pin contract-level facts, and the smoke checks above pin loading, not routing.

• The three hosts' skill catalogs are always-on context. Ten skills cost ~40 tokens each on Claude Code (claude plugin details prints the estimate); Codex shortens descriptions when its budget fills.

Docs

• goal-and-requirements.md — what this port is for, in and out of scope, acceptance criteria.

• architecture.md — drivers, decisions, invariants, out-of-scope.

• SPEC.md, core/SPEC.md, mcp/SPEC.md — the plugin's own module specs.

• NOTICE — attribution and the license each part keeps.