Skip to main content

Build with an AI coding agent

Install the Catalyst AI plugin in your AI coding agent, sign in, and start one demo. Your agent then shows you a durable workflow or agent surviving a crash, on your own Catalyst account.

Before you begin​

  • Claude Code, OpenAI Codex, or the GitHub Copilot CLI. For VS Code and other agents, see Other agents and setups.
  • Git, and a runtime for the sample's language. The starter prompts use Python by default.

Your agent does everything through the Catalyst MCP server.

1. Install​

Run the command for your agent. It installs the Catalyst AI plugin: the Catalyst skills and the Catalyst MCP server:

claude plugin marketplace add diagridio/catalyst-ai && claude plugin install catalyst-ai@diagrid

The plugin installs the skills, registers the Catalyst MCP server, and adds the /catalyst-ai:try-workflow and /catalyst-ai:try-agent commands.

2. Sign in or sign up​

Authenticate once:

Run /mcp, choose plugin:catalyst-ai:catalyst, and choose Authenticate.

Your browser opens. Sign in, or create a free account, then approve your agent's access. From then on, your agent acts as you.

If you just created your account, verify your email, open catalyst.diagrid.io once to finish setting it up, and then authenticate again.

3. Try the starter prompt​

When a process dies mid-task, you normally lose the work, or build retries, state tables, and queues to protect it. On Catalyst, it resumes where it stopped. To see it happen, start your agent and choose a demo. For Codex and the Copilot CLI, start it in the folder where you installed the skills.

In Claude Code with the plugin, run /catalyst-ai:try-workflow.

In Codex, the Copilot CLI, or Claude Code with skills from npx skills add, give your agent this prompt:

I'm new to Diagrid Catalyst. Show me a durable workflow that survives a crash, using the Catalyst MCP tools for everything in Catalyst, and your shell for git and running the app.
`<project>` in this prompt is the name, not the numeric ID, of the project settled in step 2: `default` unless step 2 settles another.
Whenever a run starts, whenever you wait for me, and at the end, give me that run's console link as a markdown link, never in backticks or a code block, so I can click it: [Run <instance-id> in Catalyst](https://catalyst.diagrid.io/workflows/<app-id>/<instance-id>?project=<project>). Put the plain URL on the line after it as well, also outside backticks, in case my terminal does not render links.
1. Call `catalyst_whoami` and tell me which org I'm signed in to. If that fails, help me sign in.
2. Check with `catalyst_list_projects` that project `default` exists, and use it if it does. If it does not, list the other projects I have and ask me to pick one or to have you create a new project for me. Only create a project if I choose that. Your Catalyst skills say not to create projects, but here I am asking you to: ask me for a name, check with `catalyst_get_usage` that I have room for another project, create it with `catalyst_apply` and a `Project` manifest (`catalyst_get_resource_schema` shows its shape), and use it from then on. Never tell me to create it myself in the console. If I have no projects, offer to create one the same way.
3. Clone https://github.com/diagridio/catalyst-quickstarts, take the durable workflow sample in my language (Python if unsure), and make sure App ID `durable-workflow` exists in project `<project>`.
4. Get its connection with `catalyst_get_connection`, write the values to a `.env` in the sample folder (gitignored), and start the sample in the background with its environment loaded from it.
5. Run one workflow to completion. Then start one through the sample's crash endpoint, show me with `catalyst_get_workflow_run` that it's RUNNING and waiting, not failed, and wait until I type continue.
6. Restart the app. When the run completes, show me from its history that finished steps ran once and only the step the crash cut off ran again.
7. Explain in at most three sentences why it survived, then offer one next step and wait for my pick.

Your agent clones a sample, runs a workflow, crashes it partway through, and shows you the run resume from where it stopped. It waits for you before the restart, and again at the end.

For a guided walk-through of what your agent does at each stage, follow a quickstart: build a workflow or run an agent.

Open the console link your agent prints to see the run.

More prompts to try​

Once the starter demo has worked, try one of these in your own project:

  • "Add a durable agent to this project that answers questions about our product, and show me it keeps the conversation after a restart."
  • "Add a human approval step to my workflow: pause until I approve, then carry on."
  • "Turn this process into a durable workflow:" followed by a description, a Mermaid diagram, or a photo of a whiteboard.
  • "Find out why my last workflow run failed, fix the code, and rerun it."
  • "Create what this app needs in Catalyst, and show me each piece is ready."

What the skills do​

SkillWhat it does
catalyst-setupConnects the session to Catalyst and confirms it works.
catalyst-workflow-scaffoldAdds a durable workflow, with its activities and project wiring, in your repository's language.
catalyst-workflow-from-diagramTurns a diagram, such as Mermaid, BPMN, or a photo of a whiteboard, into a workflow.
catalyst-agent-scaffoldAdds a durable agent.
catalyst-agent-harnessMakes your own agent loop durable: every model call and tool call becomes its own activity.
catalyst-app-tunnelsOpens an app tunnel so Catalyst can call into a process on your machine. It installs the Diagrid CLI for this one job.
catalyst-developRuns your app on your machine against Catalyst while you edit it, using connection values from the MCP server.
catalyst-deployMoves an app from your laptop into Catalyst.
catalyst-operateReads a project's apps, agents, workflow runs, logs, and quotas.
catalyst-debugDiagnoses a failing app or run, then stops, reruns, or purges runs when you ask it to.
catalyst-workflow-determinismChecks that workflow code replays safely.
catalyst-activity-idempotencyMakes activities safe to run more than once.

What your agent can change​

Your agent acts as you. It can reach the projects your account can reach, and your role limits what it can change.

The skills work through the MCP server's tools, which cover reading, deploying and deleting resources, granting and revoking access, and starting, rerunning, terminating, or purging workflow runs. Your role decides what your agent can change: a read-only role sees the 28 read-only tools, catalyst_get_connection needs write access, and the Catalyst API checks every change against your role. Tools whose changes are permanent are marked destructive, so agents that honor that mark ask you first. Deleting a project, purging runs, and rerunning several runs at once show a preview and wait for a second, confirmed call.

At the default level (Metadata), your agent sees names, statuses, and errors. The Metadata and application data level also shows workflow inputs, outputs, and custom status. See Choose how much the agent sees and Data shared with AI tools.

Other agents and setups​

  • VS Code, Claude Desktop, and claude.ai: connect them to the Catalyst MCP server. To give Copilot in VS Code the skills too, run the npx skills add part of the Copilot CLI command. Support for Cursor is coming soon.

  • Install for your user instead of one project: add -g to the npx skills add command.

  • Install for several agents at once: repeat -a for each agent:

    npx skills add diagridio/catalyst-ai -a claude-code -a codex -a github-copilot -s '*' -y

    Give each agent its own -a flag. This installs the skills. For Claude Code, use the plugin: it also registers the MCP server and adds the /catalyst-ai:try-workflow and /catalyst-ai:try-agent commands. With skills from npx skills add, give Claude Code the prompt from step 3.

  • Keep --yes in every npx skills add command, so a non-interactive run installs the skills.

Catalyst skills and Dapr Skills​

The Catalyst skills and the Dapr Skills plugin do different jobs. Dapr Skills scaffolds Dapr Workflow projects for any Dapr environment. The Catalyst skills work with your Catalyst organization: its projects, apps, and workflow runs.

Next steps​

🔌

Connect to the Catalyst MCP server

Add the hosted server to Codex, VS Code, Claude Desktop, and more.

🔁

Workflows

Understand the durable workflows your agent scaffolds.

Last updated on