Building a Data Stack Live with AI AgentsLivestream August 18

Skip to main content

Managing Dives as Code

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 like the rest of your codebase.

For repositories that contain Dives, Flights, and shared data products, use MotherDuck Blueprints. Blueprints keeps independently owned resources in typed directories, connects producers and consumers with explicit inputs and outputs, deploys complete branch-scoped previews, and updates production through GitHub Actions.

The rest of this guide also documents the smaller Dives-only starter repository. Use that workflow when your repository only manages Dives and you don't need dependency-aware Flight deployment.

Choose a repository structure​

A Blueprints repository can use this structure:

flights/
  <producer_name>/
    blueprint.yml
    src/flight.py
dives/
  <dive_name>/
    blueprint.yml
    src/dive.tsx
guides/
roles/
projects/
shared/

Use flights/, dives/, guides/, and roles/ when those resources have separate owners or deployment schedules. Use projects/ when several resources need to preview, deploy, and roll back as one unit.

A Flight package can export a share under a stable output name, and a Dive package can consume it:

# flights/events-ingest/blueprint.yml
outputs:
  events:
    share: events
# dives/events-dashboard/blueprint.yml
inputs:
  events:
    blueprint: events-ingest
    output: events

resources:
  dives:
    dashboard:
      requiredResources:
        - input: events
          alias: events

For pull requests, Blueprints expands the selection upstream and downstream so the Flight, branch-scoped share, and Dive are previewed together. In production, changing a producer redeploys its consumers, while changing only a Dive uses the existing production output without rerunning the Flight.

Start with the Dives-only repository​

Fork the Dives-only starter repository when you don't need Flight or data dependency management. 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.

Watch on YouTube

Prerequisites​

The Dives-only pull-down workflow below also requires a published Dive and Claude Code connected to the MotherDuck MCP Server. Blueprints can start from a Flight, Dive, Guide, role, or combined project and does not require an existing Dive.

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:

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

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.

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.

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

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.

If your repo includes a CLAUDE.md file (the Dives-only starter repository includes one), the agent also knows the folder conventions and how to register Dives for CI.

Deploy a preview with GitHub actions​

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

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.

A GitHub Actions bot comment on a PR showing a preview Dive link — click Open Dive to see it live in MotherDuck.

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.

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.

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.

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.