# Convert a Cursor Automation

Convert a dashboard Automation when you want to edit its behavior as
code, test it locally, or deploy it as an Agent SDK project. If you only
need to change the prompt or trigger, the dashboard remains the shorter
path.

`init --from automation:…` carries over what it can prove from the exported
configuration and prints a checklist for everything that still needs
your judgment.

## Convert and run locally

The command creates a project named after the Automation, installs its
dependencies, and prints the generated files along with warnings and
setup steps. Once `dev` starts, you can exercise the converted agent in
the playground before reconnecting any live trigger.

```text
agent-sdk login
agent-sdk init --from \
  automation:https://cursor.com/automations/0a1b2c3d-0000-1111-2222-333344445555

cd nightly-triage
agent-sdk validate
agent-sdk dev
```

The project includes the Automation's prompt and model plus any
schedules, channels, and account connections the converter could
represent directly. The
[CLI reference](/docs/reference/cli.md#convert-automation) covers custom
output directories, JSON output, and command failures.

## Reconnect account-backed actions

For an HTTP or SSE MCP server, the converter writes a name-based
connection instead of copying its URL or credentials. After you connect
the same server under MCP in Cursor and sign in the local host, the
converted agent can use that server's tools through your account.

```ts
// bot/mcp-connections/linear.ts
import { defineConnection } from "@grok/agent-sdk/connections";

export default defineConnection({
  cursorAccount: true,
  servers: ["Linear"],
});
```

The summary adds a `Verify:` step when an original dashboard action
does not map to one generated tool. Treat that step as a behavior test:
run the converted agent with a representative input and confirm the
same external write happens before you consider the action restored.

## Bring a Slack trigger online

After you create the dedicated Slack app, mentions wake the converted
agent and its answers land in the same thread. A channel watch also
wakes on allowed posts, but only after you subscribe the app with
`--channel-posts`.

```text
agent-sdk slack create --dir . --channel-posts
```

The converter preserves the watch allowlist. If a warning says Cursor
previously filtered messages by text, add that decision to the
generated channel before inviting the bot:

```ts
export default slackChannel({
  envPrefix: "NIGHTLY_TRIAGE",
  engagement: {
    channelPosts: { allow: ["C123"] },
  },
  onChannelPost: async (_ctx, message) => {
    if (!message.markdown.includes("deploy")) {
      return null;
    }
    // `{}` starts a model turn as the sender.
    return {};
  },
});
```

For mention-only Automations, run `agent-sdk slack create --dir .`
without `--channel-posts`. The [Slack guide](/docs/guides/slack.md) covers the
reply experience and app setup.

## Bring a GitHub trigger online

The generated GitHub channel keeps mechanical filters such as PR
actions, branches, issue actions, repositories, and simple user
allowlists. Conditions that depend on dashboard-only context stay
fail-closed, so the corresponding hook returns `null` until you replace
them.

For example, a converted CI trigger can wake only when the suite fails:

```ts
import {
  defaultGitHubAuth,
  githubChannel,
} from "@grok/agent-sdk/channels/github";

export default githubChannel({
  cursorAccount: { repos: ["acme/api"] },
  webhookEvents: ["check_suite"],
  onCheckSuite: (ctx, suite) => {
    if (suite.conclusion !== "failure") {
      return null;
    }
    // `auth` starts a model turn running as the sender.
    return { auth: defaultGitHubAuth(ctx) };
  },
});
```

Replay a PR with a failing check before connecting live delivery:

```text
agent-sdk github replay acme/api#42 \
  --dir . \
  --events '*' \
  --conclusion failure
```

Cursor-account delivery carries PR and comment events. Push, issue, and
CI triggers need real GitHub webhook delivery through a GitHub App or
`github forward`. The [GitHub guide](/docs/guides/github.md) covers both paths.

## Treat warnings as the migration checklist

A successful conversion means the project was generated, not that
every source behavior survived. Read the warnings and setup steps before
turning on a live trigger:

- A setup step names something you must connect or configure.

- A `Verify:` step names an external action whose behavior needs a test.

- A fail-closed hook intentionally starts no turns until you restore its
  filter.

- A `.todo.md` file is ignored by the framework and marks a connection
  you must replace.

Keep the source Automation enabled while you work through this list, so
you still have its behavior as a reference.

## Know the conversion boundary

The converter can reproduce configuration that has a direct home in an
Agent SDK project: instructions, the selected model, cron schedules,
mechanical GitHub filters, Slack mentions and watch allowlists, and
named Cursor-account MCP connections.

It cannot infer policy that lived behind the dashboard. Bespoke trigger
conditions, provider webhook registration and auth, credentials,
unsupported trigger semantics, and built-in action behavior remain
warnings, comments, or TODO files for you to resolve. Credentials are
never exported. Automation memory does not carry over. See
[RA-893](https://linear.app/xai-linear/issue/RA-893).

Cursor-managed Automations do not convert because their behavior lives
entirely in managed configuration.

## Related

- [CLI reference](/docs/reference/cli.md#convert-automation): arguments,
  JSON output, and failures
- [MCP connections](/docs/reference/connections.md): Cursor-account
  connectors and hosted authorization
- [GitHub](/docs/guides/github.md): event delivery, hook filters, and replay
- [Slack](/docs/guides/slack.md): mentions, channel watches, and reply modes
- [Webhooks](/docs/guides/webhooks.md): auth and filtering for generated provider
  routes
- [Deployment](/docs/deployment.md): deploy the reviewed project, then
  disable the source Automation before enabling the same live triggers