Diagrid Catalyst

catalyst-ai

Build and operate Diagrid Catalyst by prompting — Dapr Workflows, Durable Agents, and the running system.

Verified end to end in Claude Code — installs in under 5 seconds, every skill registers, and a real Catalyst question fires the right skill and gets a grounded answer. In Codex and GitHub Copilot the install and every skill are verified, and Codex is confirmed to put them in front of the model; neither has yet answered a Catalyst question here, for reasons that are nothing to do with the skills.

Early release. The skills drive Catalyst through the remote Catalyst MCP server:

you add the server and sign in once. The one exception is an app tunnel, which lets

Catalyst call into a process on your machine. No MCP tool opens one, so

catalyst-app-tunnels installs the Diagrid CLI and uses it for that alone. Read What works today for what is and is not available

over MCP yet.

Install

Claude Code

claude plugin marketplace add diagridio/catalyst-ai

claude plugin install catalyst-ai@diagrid

Then check it landed — both commands, not just the second:

claude plugin list                           # expect Version: 0.7.0 or later

claude plugin details catalyst-ai@diagrid # expect 12 skills

list reports the version you actually have. details reports the version the marketplace is offering, reading the installed copy only when the two agree — so on its own it can show you 12 skills while your session loads 11. If either looks wrong, jump to If your install is behind.

The same marketplace also lists dapr-skills, for Dapr applications that run outside Catalyst — see Also in this marketplace.

Then sign in to the Catalyst MCP server

The plugin also registers the Catalyst MCP server, https://mcp.cloud.r1.diagrid.io/mcp. It stays empty until you sign in once. In Claude Code, run /mcp, pick plugin:catalyst-ai:catalyst and complete the browser sign-in. There is no API key.

If you already added the server yourself with claude mcp add, remove that entry (claude mcp remove catalyst --scope user) once the plugin is installed. Otherwise you have two copies of every Catalyst tool.

The plugin requests the scopes catalyst:read catalyst:write offline_access. Without offline_access there is no refresh token, so you sign in again each time the session expires. Write tools, such as catalyst_apply, are left out of the tool list entirely when your role is read-only or the sign-in did not grant write scope. If they are missing, sign in again and approve write access; if they are still missing, your role is read-only.

Check it worked by asking: *"Who am I in Catalyst?"* The answer comes from catalyst_whoami.

Connect other clients to the remote MCP server

Every client connects to the same remote server, https://mcp.cloud.r1.diagrid.io/mcp (the r1 is required), and signs in with OAuth in the browser. The authorization server does not accept dynamic registration, so a client that tries to register itself fails. Each client below uses its registered client ID instead: codex, copilot-cli, vscode, claude-code, or claude-web for claude.ai. VS Code and the Copilot CLI can also sign in without one, because the server reads the client metadata they publish.

Each snippet below also sets an X-Catalyst-Plugin-Version header to the plugin version, which lets the server see which version of these instructions a client was set up from. It goes only on the MCP requests the client already makes. When you update the skills, update the header to match.

Install the skills for the client first (below), then:

Codex

codex mcp add catalyst --url https://mcp.cloud.r1.diagrid.io/mcp --oauth-client-id codex

codex mcp login catalyst

codex mcp add has no header flag, so add this to ~/.codex/config.toml under the server it just wrote:

[mcp_servers.catalyst.http_headers]

X-Catalyst-Plugin-Version = "0.8.1"

GitHub Copilot CLI

copilot mcp add has no client-ID flag, so add the server and then set oauthClientId in ~/.copilot/mcp-config.json:

{

"mcpServers": { "catalyst": { "type": "http", "url": "https://mcp.cloud.r1.diagrid.io/mcp", "headers": { "X-Catalyst-Plugin-Version": "0.8.1" }, "oauthClientId": "copilot-cli", "tools": ["*"] } } }

Then run /mcp inside Copilot and authenticate the catalyst server in the browser.

VS Code (Copilot Chat), in .vscode/mcp.json or your user MCP configuration:

{

"servers": { "catalyst": { "type": "http", "url": "https://mcp.cloud.r1.diagrid.io/mcp", "headers": { "X-Catalyst-Plugin-Version": "0.8.1" }, "oauth": { "clientId": "vscode" } } } }

VS Code opens a browser for authorization on the first connection. See the VS Code MCP configuration reference.

claude.ai and Claude Desktop: in claude.ai, open Settings → Connectors → Add custom connector, enter the URL above, and under Advanced settings set the OAuth client ID to claude-web. Then Connect and sign in. Claude Desktop uses the connectors of the same account. Without the client ID, the connector tries to register itself and the sign-in fails. Custom connectors cannot set request headers, so this one sends no X-Catalyst-Plugin-Version. This route gives you the MCP tools only; the skills need a client from Install. Verified on claude.ai on 2026-10-29: the connector signed in and the chat could say who was signed in to Catalyst. Claude Desktop shares those connectors but has not been tried separately.

Anything else (Gemini CLI, Zed, Antigravity and so on): add the URL as a remote (streamable HTTP) MCP server in that client's own MCP setup and use its MCP sign-in.

The server is also listed in the official MCP Registry as io.diagrid/catalyst (search the registry), so clients with a registry-backed server gallery can find it there.

GitHub Copilot CLI

npx -y skills add diagridio/catalyst-ai --agent github-copilot --skill '*' --global --yes

Use repeated `--agent` flags if you pass more than one. The comma form (-a codex,github-copilot) is what the upstream README documents, and it prints Invalid agents:, installs nothing and exits 1 — so it fails honestly, and a step checking the exit code catches it. Re-measured on 1.5.22 and 1.5.23; an earlier version of this line claimed exit 0, which was a measurement error.

The failure that *is* silent is a missing -y where nothing can answer the prompt, which is every CI runner: it prints Done!, installs zero skills, and exits 0. Pass -y, and assert a skill count rather than an exit code.

--global writes all twelve skills to ~/.copilot/skills/. Copilot should read them in every project from there. Not yet verified: we have checked only that the installer writes that directory, not that Copilot loads skills from it. Check that Copilot sees them:

copilot skill list        # expect all 12

If it shows none, run the per-project command (without --global) from the repository root.

Without --global the skills go into .agents/skills/ under the folder you ran the command in. Copilot reads project skills only at the root of the repository it is working in, so an install from a subfolder, or from a folder Copilot does not treat as that root, leaves it with no skills and no error. Don't rely on npx skills list for this — its "Agents:" line only names agents it detects as installed on your machine, so it will quietly leave out a client you haven't installed yet.

Gemini CLI, Zed and Antigravity

These read the shared .agents/skills/ project directory, not ~/.copilot/skills/, so install per project, from your repository's root:

npx -y skills add diagridio/catalyst-ai --agent github-copilot --skill '*' --yes

Without --global, the github-copilot target writes that shared directory.

VS Code (Copilot Chat)

Not yet verified: we have not checked whether VS Code Copilot Chat reads skills from ~/.copilot/skills/, from .agents/skills/ at the workspace root, or both. Until then, run the per-project command above from your workspace root, which writes .agents/skills/.

Codex

npx -y skills add diagridio/catalyst-ai --agent codex --skill '*' --yes

.agents/skills/ is Codex's project skills directory too — the installer maps codex there by design, so seeing no .codex/ created is correct rather than a failed install. Codex reads them: codex debug prompt-input renders the model-visible prompt, and all of them appear in its block with their descriptions intact, byte for byte. Codex's own guidance text says automatic skill selection is allowed by default, so you shouldn't have to name a skill — though nobody has yet confirmed that from a real session.

What is and is not verified, per client

These were measured with the first ten skills. catalyst-app-tunnels and catalyst-agent-harness have not been re-measured on these clients yet.

If you can get Codex or Copilot to answer a Catalyst question, that is the single most useful thing you can report — with the wording you used and which skill fired. A skill that never fires looks identical to a session where nothing relevant came up, which is why this needs a human rather than an installer's exit code.

Also in this marketplace: dapr-skills

This marketplace lists a second plugin, dapr-skills: the same subjects on open-source Dapr — scaffold a new app, add Dapr to an existing one, migrate a TypeScript service onto Dapr building blocks, and review Dapr Workflow, pub/sub and durable agent code that runs on your own machine under the Dapr CLI or .NET Aspire.

claude plugin install dapr-skills@diagrid

They are built to sit side by side. Each dapr-skills skill that overlaps with one here says so in its description and points at this plugin for anything that runs on Catalyst, which is meant to keep the two from both firing on the same question. Nothing in CI checks that across repos yet, so if both plugins answer one request, please report it. The dapr-skills source is pinned to a commit in marketplace.json and moves only through a reviewed change here.

Then just ask

New to Catalyst? In Claude Code, type one of these to see a crash-and-recover run end to end. Each is a single line, so there's nothing to paste:

• /catalyst-ai:try-workflow: a durable workflow crashes mid-run and resumes where it stopped.
• /catalyst-ai:try-agent: the same for a durable AI agent. It defaults to LangGraph, which needs no API key. Name a framework from catalyst-quickstarts to get that one instead: /catalyst-ai:try-agent crewai.

In other clients, paste the matching prompt from commands/. It's the same text. The agent prompt opens with "Use the agent framework I named in my message", so add that name to what you paste — Use crewai. on the end does it.

After that, you don't learn commands. Try:

Set up Diagrid Cat