How to Set Up RudderStack with Your Coding Agent

Use the rudder-setup skill to have your AI coding agent create a source, a destination, and a connection, instrument your app, and confirm a delivered event.

This guide shows you how to set up RudderStack from inside your app’s repository with an AI coding agent. The agent follows the rudder-setup skill, and the setup is done when one real event from your app reaches the destination you chose.

Prerequisites

  • A RudderStack workspace and a role that can create a Read-Write personal access token for it.
  • A coding agent: Claude Code, Codex, Cursor, GitHub Copilot in VS Code, or another agent that can run shell commands.
  • git and jq installed on your machine.
  • Node.js 22.20 or later, if you use Cursor, GitHub Copilot, or the Prompt tab with an agent other than Claude Code or Codex. The Skills CLI needs it.
  • The repository of the app that will send events. If you have no app yet, see Run the setup without an app.

You don’t need to install the Rudder CLI yourself. The skill installs the latest release in ~/.local/bin when it’s missing.

How the setup works

Three RudderStack tools work together during the setup:

ToolRole in the setup
rudder-setup skillThe instructions your agent follows, in nine steps
Rudder CLIValidates the pipeline’s YAML specs and applies them to your workspace. It signs in with your personal access token.
RudderStack MCP serverReads the source’s write key and the destination’s delivery counts. It signs in through your browser with OAuth, not with the token.

You make three decisions. The agent proposes the events to track, asks where the events go, and shows a dry run before it changes your workspace. It waits for your answer each time.

Generate a personal access token

  1. Log in to the RudderStack dashboard and go to Get started.
  2. In the Setup with Agent card, generate a personal access token. The dashboard shows the token once and fills it into the commands on the card.
Get started page with the Setup with Agent card and the three manual steps

If you already have a Read-Write token for the workspace, click I already have a token. The commands then show <your-access-token> where your token goes.

Never paste the token into your agent’s chat. The agent reads it from the RUDDERSTACK_ACCESS_TOKEN environment variable of the terminal it starts in.

Start the setup in your agent

The card has one tab for each agent. The commands below are the same ones the card copies, with a placeholder for the token.

Setup with Agent card with the Claude Code tab open
  1. Install the RudderStack plugin. It adds the skill and the MCP server.
bash
claude plugin marketplace add rudderlabs/rudder-agent-skills
claude plugin marketplace update rudder-agent-skills
claude plugin install rudder-core@rudder-agent-skills
claude plugin update rudder-core@rudder-agent-skills
  1. Start Claude Code in your app. Run both lines in one terminal.
bash
export RUDDERSTACK_ACCESS_TOKEN=<your-access-token>
cd your-customer-facing-app && claude
  1. Type the following in Claude Code, and sign in to RudderStack in your browser when it asks:
/rudder-core:rudder-setup

What the agent does

The agent starts each step with a line such as Step 3 of 9 · Goal and plan, so you can follow along.

StepWhat happensWhat you do
1. StartChecks the Rudder CLI, the token, the MCP server, and the folder it was started inSign in to RudderStack in the browser, if asked
2. ExploreFinds the app’s platform and reads what your workspace already holdsConfirm what sends the events, if the code doesn’t say
3. Goal and planProposes up to four events with their properties and where each one firesSay what you want to learn, then approve the plan
4. Destination and secretsWrites the destination spec from the settings the Rudder CLI acceptsPick a destination, and fill its secrets into a git-ignored file
5. Plan and applyValidates the specs, shows a dry run, applies them, and commitsApprove the dry run
6. InstrumentInstalls the SDK and adds one typed function for each planned eventNothing
7. Verify locallyRuns your app against a local listener and compares what it sends with the planUse the app so each event fires
8. Verify liveWaits for the write key to be accepted, then reads the delivery countsUse the app once more
9. Wrap upSummarizes the resources, the code changes, the delivery counts, and the commitsDecide whether to open a pull request

The destination question offers a webhook, Google Analytics 4, Amplitude, and Mixpanel, and accepts any other destination type that the Rudder CLI lists for your source.

A new write key can take a few minutes to be accepted. Step 8 checks the key for up to five minutes before anyone sends an event, so you don’t see 401 invalid write key errors.

What the setup adds to your repository

The setup adds these files, in separate commits for the specs and for the code:

PathContent
rudder/sources/, rudder/destinations/, rudder/connections.yamlThe pipeline as Rudder CLI specs
rudder/plan.md, rudder/plan.events.jsonYour question, the agreed events, and their property types
rudder/secrets.vars.yamlDestination secrets. Git-ignored.
.env.localThe source’s write key and the data plane URL. Git-ignored.
One analytics module in your appThe SDK setup and one typed function for each event

The agent commits only the paths it wrote, so your uncommitted work stays out of its commits. The one exception is an app that isn’t in git yet. The agent asks first, then runs git init and commits the app as it is, so the undo can revert the later commits without deleting your files.

Undo the setup

Ask the agent to undo the setup, in the same session or a later one. It reverts the commits the run made, restores the key files it changed, and removes from the workspace only the resources this run created. It shows a dry run first and stops if anything else would be removed.

Run the setup without an app

Start the agent in an empty folder and answer Not sure yet, show me an event arriving when it asks what sends the events. The agent then creates the pipeline and sends the first planned event with curl. The pipeline is real. When your app is ready, copy the rudder/ folder into its repository and run the skill again there.

Limitations

  • Destinations that connect through a sign-in in the dashboard (OAuth) can’t be created by the skill yet. The agent says so and offers a webhook for the first event.
  • For a device mode destination, the SDK sends events straight to the destination, so RudderStack reports no delivery count and step 8 can’t confirm the event.
  • The skill stops in a workspace that holds CLI-managed resources from another project. See the warning below.
rudder-cli apply deletes every CLI-managed resource in the workspace that is missing from the rudder/ folder. The agent stops when a dry run lists Removed resources:. Don’t approve an apply that removes resources you didn’t expect.

Troubleshooting

SymptomFix
The agent says RUDDERSTACK_ACCESS_TOKEN isn’t setQuit the agent, run the export line in a terminal, and start the agent again from that terminal. For Cursor and VS Code, quit the editor and open it from that terminal. To save the token once, run rudder-cli auth login instead of the export line.
The agent can’t find the RudderStack MCP toolsAn MCP server added during a session loads after a restart. Restart the agent in the same terminal and resume the conversation, for example with claude --continue or codex resume --last.
rudder-cli isn’t found after the installThe agent runs it as ~/.local/bin/rudder-cli for the session. To use it in a new terminal, add export PATH="$HOME/.local/bin:$PATH" to your shell profile.
npx skills add failsUpdate Node.js to 22.20 or later.
The setup stopped midwayRun the skill again in the same folder. It finds the specs in rudder/ and resumes.

Next steps

  • Add a Tracking Plan for the agreed events with the rudder-tracking-plans skill.
  • Check later changes to your events with the rudder-tracking-review skill. When your app’s code sends the events, step 9 offers to add a line that tells your agent to use it. The line goes into your AGENTS.md, or into CLAUDE.md when that is the file you have. The agent doesn’t commit the line, and an undo leaves it in place.
  • Add a second destination. It’s one more spec in rudder/destinations/ and one more line in rudder/connections.yaml.

See more

Questions? Let's figure it out together.

Join the RudderStack Slack community to connect with other users, customers, and the RudderStack team — or reach out for direct support.