---
sidebar_position: 4
title: Managing Dives as Code
description: Set up a Git-based workflow for developing, previewing, and deploying Dives with GitHub Actions and Claude Code
feature_stage: preview
---

import VideoPlayer from '@site/src/components/VideoPlayer';

Creating Dives through an AI agent is fast, but as your team relies on them for decision-making, you may want the same rigor you apply to production code: version history, code review, and automated deployments. Since Dives are React components and SQL queries under the hood, you can manage them with Git and CI/CD — just like the rest of your codebase.

This guide walks through setting up that workflow: local development with hot reload, PR-based preview deployments, and automated production updates on merge. A [starter repo](https://github.com/motherduckdb/blessed-dives-example) with GitHub Actions pipelines is ready to fork and use.

## Quick start

Fork the [starter repo](https://github.com/motherduckdb/blessed-dives-example) to get up and running immediately. It includes:

- A working example Dive
- The Vite preview setup for local development
- GitHub Actions for deploy and cleanup
- A `CLAUDE.md` that teaches the agent the repo conventions

Fork the repo, set a `MOTHERDUCK_TOKEN` secret, and you're deploying Dives on merge.

<VideoPlayer
  playbackId="VZIfavcF0200cYrzg6JG4ln1i6wwLDDmXc1yeApyGM1Yk"
  title="CI/CD with Dives"
  thumbnailTime={4}
  youtubeUrl="https://youtu.be/61ouqduhIbc"
/>

## Prerequisites

- A [MotherDuck account](https://app.motherduck.com) with at least one Dive already published
- A GitHub repository to store your Dive source files (or fork the [starter repo](https://github.com/motherduckdb/blessed-dives-example))
- [Claude Code](https://docs.anthropic.com/en/docs/build-with-claude/claude-code/overview) connected to the [MotherDuck MCP Server](/key-tasks/ai-and-motherduck/mcp-setup/)
- A MotherDuck API token set as a GitHub secret (`MOTHERDUCK_TOKEN`)

## Pull a dive for local development

Start with a Dive that's already published in MotherDuck. Copy its share link from the MotherDuck UI, then tell Claude Code to set it up locally:

```text
Set up this dive for local development: https://app.motherduck.com/dives/...
```

<VideoPlayer
  playbackId="VZIfavcF0200cYrzg6JG4ln1i6wwLDDmXc1yeApyGM1Yk"
  title="Pulling a Dive for local development"
  thumbnailTime={100}
  assetStartTime={43}
  assetEndTime={137}
/>

The agent uses the MotherDuck MCP Server to:

1. Read the Dive source through the SQL API using the share link
2. Pull down the file into a local directory in your repo
3. Register the Dive for CI
4. Start a lightweight Vite development server for live preview

The MCP Server's `get_dive_guide` tool provides the agent with everything it needs — the React component contract, dependency setup, and instructions for the local dev server. No additional skills or context files are required beyond what the MCP server provides.

![Claude Code spinning up the Vite dev server after pulling down a Dive for local development.](./img/claude_code_vite_terminal_1ffa9f80a9.png)

## Edit locally with an AI agent

With the local dev server running, you can iterate on the Dive using Claude Code. The agent can restyle charts, rewrite SQL queries, add filters, swap visualizations — anything you can express as a prompt.

```text
Make this much better visually. Top-tier style please.
```

<VideoPlayer
  playbackId="VZIfavcF0200cYrzg6JG4ln1i6wwLDDmXc1yeApyGM1Yk"
  title="Editing a Dive locally with Claude Code"
  thumbnailTime={170}
  assetStartTime={137}
  assetEndTime={200}
/>

The Vite dev server hot-reloads changes, so you see updates instantly in the browser. The MCP server provides schema context so the agent writes accurate SQL against your live data.

![A Dive running locally, showing the updated dashboard with improved styling and layout.](./img/dive_local_preview_9bccdb19bf.png)

If your repo includes a `CLAUDE.md` file (the [starter repo](https://github.com/motherduckdb/blessed-dives-example) includes one), the agent also knows the folder conventions and how to register new Dives for CI — so you can go from "pull this Dive down" to "push up a PR" without explaining any plumbing.

## Deploy a preview with GitHub actions

Once you're happy with your changes, tell the agent to push a PR:

```text
Put up a PR on a new feature branch
```

When a PR is opened (or updated with new commits), a GitHub Action detects which Dive folders changed and deploys a **preview** Dive to MotherDuck. The preview uses the same live environment as production but has a branch-tagged title so it's clearly labeled. A comment appears on the PR with a direct link.

<VideoPlayer
  playbackId="VZIfavcF0200cYrzg6JG4ln1i6wwLDDmXc1yeApyGM1Yk"
  title="PR preview deployment for Dives"
  thumbnailTime={218}
  assetStartTime={200}
  assetEndTime={238}
/>

![A GitHub Actions bot comment on a PR showing a preview Dive link — click Open Dive to see it live in MotherDuck.](./img/pr_preview_comment_13ca302ff9.png)

Your reviewer clicks the link and sees the Dive running with live queries — no local setup needed.

The deploy action uses path filters to detect which Dive folders changed, then calls a shared deploy script (`scripts/deploy-dive.sh`) for each one. The script reads the Dive's source and metadata, and uses the DuckDB CLI with the MotherDuck extension to create or update the Dive.

## Merge to production

When the preview looks right, merge the PR. A separate deploy job runs that creates or updates the production Dive, matched by title.

<VideoPlayer
  playbackId="VZIfavcF0200cYrzg6JG4ln1i6wwLDDmXc1yeApyGM1Yk"
  title="Merging a Dive to production"
  thumbnailTime={245}
  assetStartTime={244}
  assetEndTime={255}
/>

The production Dive is now live and shareable with anyone in your organization.

![The deploy GitHub Action after a merge to main, completing in 20 seconds.](./img/deploy_action_success_f763894ae0.png)

## Clean up preview dives

Delete the feature branch after merging. A cleanup action fires that removes the preview Dive from your MotherDuck account — no orphaned Dives cluttering your workspace.

<VideoPlayer
  playbackId="VZIfavcF0200cYrzg6JG4ln1i6wwLDDmXc1yeApyGM1Yk"
  title="Cleanup on branch deletion"
  thumbnailTime={265}
  assetStartTime={259}
/>

The entire pipeline is two GitHub Actions and one secret (`MOTHERDUCK_TOKEN`). At MotherDuck, we use a dedicated service account so anyone with repo access can edit and deploy with the same ownership scope.

## Related resources

- [Creating Visualizations with Dives](/key-tasks/ai-and-motherduck/dives/) — Create Dives from natural language with AI agents
- [Dives SQL Functions](/sql-reference/motherduck-sql-reference/ai-functions/dives/) — Manage Dives directly from SQL
- [Connect to MCP Server](/key-tasks/ai-and-motherduck/mcp-setup/) — Set up the MCP server with your AI assistant
- [Starter repo](https://github.com/motherduckdb/blessed-dives-example) — Fork and start deploying