Build with an AI coding agent
Install the Diagrid 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 Diagrid 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 Diagrid MCP server.
1. Install
Run the command for your agent. It installs the Diagrid AI plugin: the skills and the Diagrid MCP server:
- Claude Code
- Codex
- Copilot CLI
- macOS/Linux
- Windows
claude plugin marketplace add diagridio/diagrid-ai && claude plugin install diagrid@diagrid
claude plugin marketplace add diagridio/diagrid-ai
claude plugin install diagrid@diagrid
The plugin installs the skills, registers the Diagrid MCP server, and adds the /diagrid:try-workflow and /diagrid:try-agent commands.
- macOS/Linux
- Windows
npx skills add diagridio/diagrid-ai --agent codex --skill '*' --yes && codex mcp add diagrid --url https://mcp.cloud.r1.diagrid.io/mcp --oauth-client-id codex
npx skills add diagridio/diagrid-ai --agent codex --skill '*' --yes
codex mcp add diagrid --url https://mcp.cloud.r1.diagrid.io/mcp --oauth-client-id codex
This installs the skills into .agents/skills/ in the current project, and adds the Diagrid MCP server.
- macOS/Linux
- Windows
npx skills add diagridio/diagrid-ai --agent github-copilot --skill '*' --yes && copilot mcp add --transport http diagrid https://mcp.cloud.r1.diagrid.io/mcp
npx skills add diagridio/diagrid-ai --agent github-copilot --skill '*' --yes
copilot mcp add --transport http diagrid https://mcp.cloud.r1.diagrid.io/mcp
This installs the skills into .agents/skills/ in the current project, and adds the Diagrid MCP server. Then open ~/.copilot/mcp-config.json and add "oauthClientId": "copilot-cli" to the diagrid entry, so Copilot signs in with its registered client ID:
{
"mcpServers": {
"diagrid": {
"type": "http",
"url": "https://mcp.cloud.r1.diagrid.io/mcp",
"oauthClientId": "copilot-cli",
"tools": ["*"]
}
}
}
If you installed the plugin or the skills before they were renamed from catalyst-ai, move to the new names, so your agent doesn't see every skill twice.
2. Sign in or sign up
Authenticate once:
- Claude Code
- Codex
- Copilot CLI
Run /mcp, choose plugin:diagrid:diagrid, and choose Authenticate.
codex mcp login diagrid
Run /mcp, choose diagrid, 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 Diagrid, 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.
- Durable workflow
- Durable agent
In Claude Code with the plugin, run /diagrid: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. Show me a durable workflow that survives a crash, using the Diagrid MCP tools for everything in Diagrid, 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 Diagrid](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 `diagrid_whoami` and tell me which org I'm signed in to. If that fails, help me sign in.
2. Check with `diagrid_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 Diagrid skills say not to create projects, but here I am asking you to: ask me for a name, check with `diagrid_get_usage` that I have room for another project, create it with `diagrid_apply` and a `Project` manifest (`diagrid_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 `diagrid_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 `diagrid_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.
In Claude Code with the plugin, run /diagrid:try-agent.
In Codex, the Copilot CLI, or Claude Code with skills from npx skills add, give your agent this prompt:
I'm new to Diagrid. Show me a durable AI agent that survives a crash, using the Diagrid MCP tools for everything in Diagrid, and your shell for git and running the app.
Use the agent framework I named in my message. If I named none, use `langgraph`, which runs on a built-in offline model and needs no API key. The frameworks with a crash-test sample are `adk`, `claude-agents`, `crewai`, `deepagents`, `langgraph`, `mastra`, `microsoft-dotnet`, `openai-agents`, `pydantic-ai`, `spring-ai` and `strands`. `langgraphjs`, `langchaingo` and `dapr-agents` have no crash-test sample, so if I ask for one of those, say so in one sentence and offer me the list above. If I name anything else, do not guess a folder: tell me you do not recognise it and offer me that list.
`<project>` in this prompt is the name, not the numeric ID, of the project settled in step 2: `default` unless step 2 settles another. `<agent>` and `<port>` are settled in step 3; do not assume them, because they differ per framework.
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 Diagrid](https://catalyst.diagrid.io/workflows/<agent>/<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 `diagrid_whoami` and tell me which org I'm signed in to. If that fails, help me sign in.
2. Check with `diagrid_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 Diagrid skills say not to create projects, but here I am asking you to: ask me for a name, check with `diagrid_get_usage` that I have room for another project, create it with `diagrid_apply` and a `Project` manifest (`diagrid_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 and take the sample folder `agents/<framework>`, except for `spring-ai`, whose folder is `agents/spring-ai/crash-recovery`. In that folder, read `dev-crash-test.yaml` (spring-ai calls its copy `dev-spring-ai-crash-recovery.yaml`, and microsoft-dotnet `dev-dotnet-agent.yaml`) for the sample's `appID`, `appPort` and start command — those are `<agent>` and `<port>` — and read `test.http` for the shape of the crash request you send in step 6. Create nothing in Diagrid yet.
4. Read that folder's README for the API key it needs. `langgraph`, `spring-ai` and `microsoft-dotnet` ship an offline model and need none. If the one I picked needs a key, take it from the environment you already have: test only whether the variable is set, never printing its value (`test -n "$<VAR>"` in a POSIX shell, `Test-Path Env:<VAR>` in PowerShell, where `<VAR>` is the variable that README names), and never ask me to paste it into this chat. If it is not there, tell me which variable to set, say that I have to set it and start you again for you to see it, offer `langgraph` instead in the meantime, and wait for my answer before going on. If I take that offer, redo step 3 for `langgraph` — its folder, `<agent>`, `<port>`, start command and `test.http` — before step 5.
5. Now that the framework is settled, make sure agent `<agent>` exists in project `<project>` with `diagrid_apply`. Diagrid provides its state, pub/sub and registry, so apply only the agent itself. Install the sample's dependencies the way its README says. Get its connection with `diagrid_get_connection` and write those values, and only those, to a `.env` in the sample folder: the API key stays in the environment the sample inherits, so it never reaches the disk. Before writing, check the file is ignored with `git check-ignore .env`, and stop and tell me if it is not. Then start the sample in the background on `<port>` with the start command from step 3, its environment loaded from that file.
6. Start a run with `POST /crash/run`, sending the body `test.http` shows for this sample with `kill_after_seconds` added, so the agent dies mid-run. Show me with `diagrid_get_workflow_run` that the run is RUNNING and waiting, not failed, and wait until I type continue.
7. Restart it the same way. When the run completes, show me from its history that the steps finished before the crash ran once and only the one it cut off ran again.
8. Explain in at most three sentences why it survived, then offer one next step and wait for my pick.
Your agent clones the LangGraph sample, starts an agent run, kills it partway through, and shows you the run resume from where it stopped. The sample uses a built-in offline model, so it runs as is. 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 Diagrid, and show me each piece is ready."
What the skills do
In Claude Code, the plugin's skills show up with the plugin name in front, for example diagrid:diagrid-deploy.
| Skill | What it does |
|---|---|
diagrid-setup | Connects the session to Diagrid and confirms it works. |
diagrid-workflow-scaffold | Adds a durable workflow, with its activities and project wiring, in your repository's language. |
diagrid-workflow-from-diagram | Turns a diagram, such as Mermaid, BPMN, or a photo of a whiteboard, into a workflow. |
diagrid-agent-scaffold | Adds a durable agent. |
diagrid-agent-harness | Makes your own agent loop durable: every model call and tool call becomes its own activity. |
diagrid-app-tunnels | Opens an app tunnel so Diagrid can call into a process on your machine. It installs the Diagrid CLI for this one job. |
diagrid-develop | Runs your app on your machine against Diagrid while you edit it, using connection values from the MCP server. |
diagrid-deploy | Moves an app from your laptop into Diagrid. |
diagrid-operate | Reads a project's apps, agents, workflow runs, logs, and quotas. |
diagrid-debug | Diagnoses a failing app or run, then stops, reruns, or purges runs when you ask it to. |
diagrid-workflow-determinism | Checks that workflow code replays safely. |
diagrid-activity-idempotency | Makes 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, the tool that returns an app's connection values needs write access, and the Diagrid 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 resource, 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 Diagrid MCP server. To give Copilot in VS Code the skills too, run the
npx skills addpart of the Copilot CLI command. Support for Cursor is coming soon. -
Install for your user instead of one project: add
-gto thenpx skills addcommand. -
Install for several agents at once: repeat
-afor each agent:npx skills add diagridio/diagrid-ai -a claude-code -a codex -a github-copilot -s '*' -yGive each agent its own
-aflag. This installs the skills. For Claude Code, use the plugin: it also registers the MCP server and adds the/diagrid:try-workflowand/diagrid:try-agentcommands. With skills fromnpx skills add, give Claude Code the prompt from step 3. -
Keep
--yesin everynpx skills addcommand, so a non-interactive run installs the skills.
Diagrid skills and Dapr Skills
The Diagrid skills and the Dapr Skills plugin do different jobs. Dapr Skills scaffolds Dapr Workflow projects for any Dapr environment. The Diagrid skills work with your Diagrid organization: its projects, apps, and workflow runs.