Skip to main content

Local development with AI agents

Introduction​

Holistics supports using a coding agent (Claude Code, Cursor, GitHub Copilot, Codex) for BI development. You edit AML locally in your IDE, the Holistics CLI keeps those files and your commits in continuous sync with your Holistics project, and Holistics tools give the agent access to your workspace to run queries, get sample data, or inspect data warehouse schemas.

You don't need a GitHub or GitLab repo. The CLI downloads your project straight from Holistics.

Three moving parts:

  • Holistics CLI: two-way sync of files and commits between your local folder and Holistics
  • Holistics tools: live workspace access for the agent (explore models, run AQL, inspect schemas), through the CLI or the MCP server
  • Holistics skills: reusable AML/AQL workflows the agent can invoke. The holistics-development skill also installs the CLI, logs you in, downloads your project and starts the sync.
Prefer a plain IDE, no agent?

The CLI sync workflow stands on its own. Install the Holistics CLI, then run:

holistics auth
holistics sync init
cd <folder-from-init>
holistics sync start --background

holistics sync init downloads the project you logged in to with holistics auth. It asks for a folder name and suggests your project name.

Prerequisites​

Before you begin, make sure you have:

  • A Holistics project
  • A coding agent (Claude Code, Cursor, GitHub Copilot, Codex). Optional if you only want IDE + sync.

How it fits together​

Setup​

Setup takes two steps. You install the Holistics skills, then one skill installs the CLI, downloads your project and starts sync.

1. Install Holistics skills​

Open Claude Code in the folder where you want to keep your Holistics project. If you already have the project locally (for example, a clone of your GitHub repo), open that folder instead.

Run the commands below one at a time (Claude Code only accepts a single slash command per submission, so do not paste them together).

First, add the holistics/skills marketplace:

/plugin marketplace add holistics/skills

Then install the holistics-development plugin to develop your AMQL project (models, datasets, and dashboards) with your agent:

/plugin install holistics-development@holistics-skills

To also ask data questions on published datasets and dashboards from Claude Code, install the holistics-reporting plugin too:

/plugin install holistics-reporting@holistics-skills

Prefer the interactive menu? Run /plugin, then browse to holistics-skills and select the plugins you need.

For other AI agents, see Skills and plugins.

By default, the agent hands AQL and visualization writing to Holistics AI. The plugin also has an option to let the agent write them itself. See Choose who writes AQL and visualizations for how each option is billed and how to set it.

Restart Claude Code before continuing

Claude Code only loads a plugin's skills at session start, so /setup-amql-development won't be available yet in the session that just installed the plugin. Restart Claude Code now, reopen the folder, and continue with step 2 in the new session.

If you're driving this setup via an agent (rather than typing the commands yourself), have it stop here and ask you to restart Claude Code, rather than working around the missing skill by reading the skill files directly from disk.

2. Run /setup-amql-development​

Trigger the skill in Claude:

/setup-amql-development

The skill walks you through and automatically handles:

  • Installing the Holistics CLI and logging you in
  • Downloading your Holistics project into a new local folder with holistics sync init (the skill asks before it runs this)
  • Starting the sync in the background with holistics sync start --background

Follow the prompts from the skill. When it completes, your agent is connected to your workspace and the sync is running.

For details of every sync command and option, see CLI: sync.

Daily workflow​

With the pieces above wired up, the loop looks like:

   ╭─────────────────╮     describe change      ╭──────────────────╮
   │       You       │ ───────────────────────▶ │   Coding Agent   │
   ╰────────▲────────╯                          ╰─────────┬────────╯
            │                                             │
   preview  │                                             │ explore + query
   + tweak  │                                             │ (CLI + Skill)
            │                                             ▼
   ╭────────┴────────╮                          ╭──────────────────╮
   │  Holistics UI   │                          │  Local AML files │
   │   (dev branch)  │                          │     (in IDE)     │
   ╰────────▲────────╯                          ╰─────────┬────────╯
            │                                             │
            │              holistics sync                 │
            ╰─────────────────◀───────────────────────────╯
                       two-way sync
  1. Describe the change you want to your agent: a new model, a new metric, a dashboard tweak.
  2. The agent explores your workspace with Holistics tools, edits AML files locally, and follows the patterns from the installed skills.
  3. holistics sync sends each save to your Holistics dev branch within seconds.
  4. Preview in the Holistics UI. Any tweaks you make there sync back to your local files.
  5. Iterate with the agent until the change is ready.

Work on a new branch​

Create the branch locally:

git checkout -b feature/add-new-dashboard

Sync notices that your local branch and the Holistics branch differ. It pauses and asks which one to use. Run holistics sync status to see the exact holistics sync input command for each choice, then run the one you want. Sync restarts on that branch.

Ship to production​

When the change looks right in the Holistics preview, commit it and publish it.

Commit​

When your change is ready, commit it locally or in the Holistics UI. Sync carries commits both ways, so the commit shows up on the other side too.

git add .
git commit -m "Add new sales dashboard"

Publish​

Publish either:

  • Manually through the Holistics UI
  • Call the Publish API from a script

Review with pull requests (optional)​

If your project is also connected to a GitHub or GitLab repo, you can review changes with pull requests before publishing:

Tooling​

Validation​

You can validate your AML at any time, either locally with the CLI or in CI/CD with the Validation API:

  • CLI validation for local validation:

    holistics aml validate

  • Validation API for project-level validation in CI/CD pipelines:

    curl -X POST https://<holistics domain>/api/v2/aml_studio/projects/submit_validate \
      -H "X-Holistics-Key: $HOLISTICS_API_KEY" \
      -d '{
        "branch": "feature/add-new-dashboard"
        "commit-oid": "abc123def456",
      }'

Both approaches integrate cleanly into CI/CD workflows. For example, you can set up a GitHub Action to run holistics aml validate on every push to ensure code quality before merging.

Publish​

Trigger a publish from a script or CI/CD using the submit_publish endpoint. The endpoint returns a job ID that you can poll via /jobs/<id>/result for completion.

curl -X POST \
  -H "X-Holistics-Key: $HOLISTICS_API_KEY" \
  -H "Content-Type: application/json" \
  "https://<your-holistics-domain>/api/v2/aml_studio/projects/submit_publish"

Expected response:

{
  "job": {
    "id": "abc123",
    "status": "running"
  }
}

Pair this with the Validation API on PRs and an auto-publish action on merge for end-to-end CI/CD. See Auto-publish on merge for a full GitHub Action example.

VS Code extension​

The Holistics VS Code extension adds IntelliSense, hover docs, go-to-definition, and real-time diagnostics for AML. Useful for human-authored edits, and agents running inside VS Code or Cursor pick up the same hover info and definitions as extra context.

Lineage​

Coming soon

holistics aml lineage will let you dump your project's lineage graph as JSON for refactor planning and integrations with external metadata tools. Stay tuned.

Troubleshooting​

/setup-amql-development not found right after installing the plugin​

Claude Code loads plugin skills only at session start. If you just ran the /plugin install commands from step 1, restart Claude Code and reopen the folder before running /setup-amql-development. The skill isn't available in the same session that installed it.

Changes not appearing in Holistics​

  • Run holistics sync status. It says whether sync is running and what to do next.
  • If sync is not running, start it again with holistics sync start --background
  • Make sure you're previewing the same branch that sync is on

Sync stopped and is waiting for input​

This happens when your local branch and the Holistics branch differ. Run holistics sync status, pick one of the holistics sync input commands it lists, and run it. Sync restarts.

Conflicts​

Conflicts happen when the same lines change locally and in Holistics. Resolve them without stopping sync. Restarting resolves nothing.

  1. Open the conflicted file and fix the conflict markers.
  2. Run git add <file>. Saving alone is not enough.
  3. If holistics sync status shows an open merge, run git commit once every file is resolved. Sync resumes.

Sync stopped during a rebase or detached HEAD​

A rebase, cherry-pick, revert or detached HEAD stops sync. Finish the git operation, then run holistics sync start --background again.

Validation errors​

  • Run holistics aml validate locally before committing
  • Check the AML reference for syntax details

What's next​

Open Markdown
Let us know what you think about this document :)