Skip to main content

Local development with AI agents

Introduction​

Local agentic BI development brings your coding agent (Claude Code, Cursor, GitHub Copilot, Codex) into your Holistics workflow. The agent edits AML on disk. The MCP server gives it live access to your workspace (datasets, models, AQL execution). The Holistics CLI keeps local files in continuous sync with a Holistics dev branch, so your in-app preview updates as the agent works.

Three pieces wire this together:

  • Holistics CLI: continuous bidirectional sync between local files and a Holistics dev branch
  • MCP server: live workspace access for the agent (explore models, run AQL, inspect schemas)
  • Holistics skills: reusable AML/AQL workflows the agent can invoke
Prefer a plain IDE, no agent?

The CLI sync workflow stands on its own. Follow steps 1–3 below to get continuous sync between VS Code (or any editor) and Holistics, and skip the MCP + skills setup in steps 4–5.

Prerequisites​

Before you begin, make sure you have:

How it fits together​

Setup​

1. Enable Git Workflow and connect repository​

In Holistics, enable Git Workflow for your project and connect it to an external Git repository (GitHub, GitLab, or Bitbucket).

This is a one-time setup per project.

See Connect to an external Git repository for the full guide.

2. Set up your local project​

Clone the repository, create a branch, and open it in your IDE:

git clone [email protected]:your-org/your-holistics-repository.git
cd your-holistics-repository
git checkout -b feature/add-new-dashboard

A typical project structure looks like:

your-holistics-repository/
├── models/
│   ├── orders.model.aml
│   └── users.model.aml
├── datasets/
│   └── ecommerce.dataset.aml
└── dashboards/
    └── sales_overview.page.aml

3. Authenticate the CLI and start the sync​

First, authenticate the CLI with your Holistics API key (find it under Account Settings in Holistics).

Pick your region:

App domain

holistics auth secure <api_key>

A successful auth prints:

Logging into https://<secure/us/eu>.holistics.io
Authentication successful. Info:
- ID: 12345
- Email: [email protected]
- Server URL: https://<secure/us/eu>.holistics.io

See Holistics CLI for full auth options.

Then, from the project root, start continuous bidirectional sync between your local files and the Holistics cloud dev branch:

holistics sync-code .

Leave this running in a terminal tab while you work. Local file saves push to the cloud within seconds, and the browser preview updates without a manual refresh. Edits made in the Holistics UI flow back to your local files automatically.

To stop the sync, press Ctrl+C.

4. Connect the MCP server to your agent​

The Holistics MCP Server gives your coding agent live, read-only access to your Holistics workspace. With it connected, the agent can:

  • Explore datasets, models, and dimensions before suggesting changes
  • Execute AQL queries to validate logic against real data
  • Execute visualizations
  • Inspect data sources and table schemas
  • Search Holistics docs

Without MCP, the agent is guessing at your AML from filenames and conventions. With it, the agent can read your actual models and run AQL before suggesting changes. See the MCP Server guide for setup in Claude Code, Cursor, Codex, and other clients.

5. Install Holistics skills​

The holistics/skills repo packages reusable AML/AQL/analytics workflows as plugins your agent can invoke. The most relevant one for local development:

  • holistics-development: building AMQL projects (models, datasets, dashboards) with coding agents

Install in Claude Code via the plugin marketplace:

/plugin marketplace add holistics/skills

Then install via /plugin > Marketplaces > holistics-skills > Browse plugins > holistics-development.

For other AI agents, import the skill files directly from the repo.

Daily workflow​

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

  1. Open your project in your agent and describe the change you want: a new model, a new metric, a dashboard tweak.
  2. The agent explores your workspace through MCP, edits AML files locally, and follows the patterns from the installed skills.
  3. sync-code pushes 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.

Ship to production​

Commit and push​

When your change is ready for review, commit and push your branch:

git add .
git commit -m "Add new sales dashboard"
git push -u origin feature/add-new-dashboard

Then open a pull request through:

  • Your Git tooling (gh pr create, GitLab CLI, etc.)
  • Your Git host's web UI (GitHub, GitLab, etc.)
  • The Holistics web UI

Code review and merge​

Have your team review the changes. Once approved, merge to your master branch.

Publish​

Publish either:

  • Manually through the Holistics UI
  • Set up a GitHub Action to auto-publish on merge using the Publish API
  • Call the Publish API locally

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​

We offer a VS Code extension that supports syntax highlighting, autocomplete, hover information, and go-to-definition. It's useful for human-authored edits, and agents running inside VS Code or Cursor can pick up the same hover info and definitions as extra context.

Holistics VS Code extension

To install, search for "Holistics" in the VS Code Extensions marketplace, or run:

code --install-extension holistics.holistics-aml-vscode-ext

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​

Changes not appearing in Holistics​

  • Confirm holistics sync-code . is still running in your terminal (it stops on Ctrl+C or when the terminal closes)
  • Make sure you're previewing the same branch the sync is configured for
  • If sync-code is not running, you can fall back to git commit && git push and switch branches in the Holistics UI to preview

Validation errors​

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

Merge conflicts​

  • If both local and UI changes were made on the same branch, resolve conflicts locally with git pull --rebase before pushing

What's next​

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