# Build a module with a coding agent, start to finish

The whole loop for Claude, Claude Code or Cursor: connect, read the SDK, plan, build, check, deploy to your workspace, test, ship new versions and submit to the Marketplace.

This page walks through building a module with a coding agent such as **Claude Code**, **Cursor** or **Claude**, from the first idea to a Marketplace listing: what to ask the agent, the connector tool it uses and the matching `dv` command.

You need to be a **Workspace Admin**. Only admins get the module-building tools.

## A prompt to start with

Paste this into your coding agent once the connector is set up:

> Use the Data Visions connector. Read the Module SDK with sdk_doc, starting with skills/starting-a-module/SKILL.md, then ask me what the module should do. Agree a short plan with me before you write any files. Check the module and ask me before you deploy it to our workspace.

To change a module you already have, name it instead: *"Check out our Tool Calibration module and add a due-date reminder."*

## 1. Connect

Add the connector to your agent with your workspace's connector address (**System settings > Marketplace > Connect your AI > Copy**). See [The Data Visions connector (MCP)](article:bae9542d-06d2-45f3-a4d5-506872f3bfde).

For the agent to deploy or check in, three things must allow it: your workspace's **AI connectors** setting must be **Read and make changes**, you must allow changes when you connect, and your role must be Workspace Admin. See [Security: AI connectors](article:cc965b81-cdc0-4970-89ee-6ac862a413f2).

Agents with a terminal can also use the CLI: ask the agent to set it up (it uses the connector's `cli_setup` tool). See [Install and sign in to the CLI](article:9b9b3a9f-142d-4159-aae3-a9414adb33fc).

## 2. Read the SDK

Ask: *"Read the Module SDK before you start."* The agent calls `sdk_doc` with no path for the index, then reads `skills/starting-a-module/SKILL.md` and `SKILL.md`. See [The Module SDK](article:92da1335-5139-4bf1-8e35-dec5d5556947).

## 3. Plan a new module, or check out an existing one

**A new module.** The starting-a-module guide has the agent coach you before it builds:

- What problem you want solved, who uses it, and how it is done today. Share an example sheet or form if you have one.
- What the platform already gives you (dashboards, forms, file storage, an AI agent, schedules, roles), so it isn't rebuilt.
- A short plan: screens, tables, who can do what, reports, and what to leave for later.

No files until you agree the plan. Keep version 1 small enough to deploy the same day. If the module code it wanted is taken (the module list includes other publishers' Marketplace modules), it picks another.

**An existing module.** Ask: *"Check out our <name> module."* The agent calls `checkout_module`, which returns the latest code and the **base** a check-in must name. With the CLI, `dv modules checkout <code>` puts the code in a new folder. You can check out only modules your workspace owns, not Marketplace modules.

## 4. Build it

A module is one folder named after its module code in lower case:

| File or folder | What it holds |
|---|---|
| `module.json` | The manifest: identity, version, permissions, tables, agent, screens. See [Module manifest (module.json) reference](article:42e987e5-382d-4d07-ab9b-13a60b831dee). |
| `api.py` | The module's web routes. Every route requires a permission. |
| `service.py` | Business logic, reading and writing the module's own tables. |
| `schemas.py` | The shapes of requests and responses. |
| `services.py` | Services the module offers other modules, and scheduled jobs. |
| `ai/tools.py` | Tools for the module's AI agent. |
| `ai/skills/` | Skills for the agent, dataset packages for dashboards, and report templates. |
| `ui/` | The pages, including the required icon (`ui/icon.svg`) and an optional settings page. |
| `qa/procedures.json` | Who uses the module and what to test. Required for the Marketplace. |
| `tests/` | Tests that run without the platform or a database. |

`module.json`, `api.py`, `service.py` and `schemas.py` are required. The agent usually starts from the SDK's example module, `examples/assets/`, under a new module code, and builds in small steps.

## 5. Validate

Ask: *"Validate the module."* The agent calls `validate_module`, or runs `dv modules validate <folder>`. This runs the quick, automatic checks without deploying. Each finding says what is wrong, why and how to fix it.

**Recommendations** are your decision, such as whether to publish the module's data to dashboards. The agent should ask you, never decide for you.

With the CLI installed, the agent can also run the module's tests with `pytest`, and the security scanners with `dv modules scan <folder>`.

## 6. Run the module check

Ask: *"Run the module check."* The agent calls `review_module`, or runs `dv modules review <folder>`. This is the same check every deploy must pass: the validator, the security scanner, known-vulnerable libraries and an AI code review. It takes a minute or more.

It returns a **must-fix** list and a count of advisories that don't block. Fix every must-fix item and run it again; deploying the same files reuses the result. `dv modules rules` shows the rules the AI review applies. A finding that truly doesn't apply can be appealed to Data Visions staff with `escalate_module_review` (or `dv modules escalate <sha256> --reason "..."`). See [Publish a module: the module check](article:cfb41dcb-edee-4f32-979c-d0f041eff1f8).

## 7. Deploy to your own workspace

Ask: *"Deploy it to our workspace."* The agent should ask you first, then call `deploy_module`, or run `dv modules deploy <folder>`.

**The first deploy needs a subscribe.** Deploying registers the module in your workspace; subscribing turns it on, creates its tables, adds its permissions to roles and puts it in the sidebar.

- Connector: `deploy_module` with `subscribe` set to true.
- CLI: `dv modules deploy <folder> --subscribe <your-workspace-slug>`. `dv dev status` shows the slug.

Later versions deploy without the subscribe. A deploy can take a few minutes while your workspace's sandbox restarts with the new code. You can deploy only to your own workspace.

Through the connector, a module can be up to about 8 MB or 400 files. Deploy larger ones with the CLI.

## Check in or deploy?

| | Check in | Deploy |
|---|---|---|
| Tool | `checkin_module`, or `dv modules checkin` | `deploy_module`, or `dv modules deploy` |
| Goes live | No. It becomes the next revision of the module's draft. | Yes, for your workspace. |
| Next step | A Workspace Admin previews and publishes it in the Module Builder. | Open it from the sidebar. |
| Use when | Others are working on the same module, or someone should look before it goes live. | You own the change and want it running. |

A check-in names the base it started from. If someone else checked in or published first, it is refused: the agent checks out again (or runs `dv modules pull`), redoes its change on the new code and checks in again. See [Several people changing one module](article:b6d833a3-f770-4064-81f5-1152f4bd529f).

## 8. Try it

Every module runs in your workspace's own sandbox. Open it from the sidebar and use it the way your people will. If a page is missing or a tool says *Permission denied*, give yourself a role that holds the module's permissions in **Users and roles**.

With the CLI, `dv modules preview <code>` opens the module in your browser.

## 9. Read the logs

When something fails, ask: *"Show me the module's logs."* The agent calls `module_logs`, which returns the latest lines from your workspace's sandbox (200 by default, up to 1,000). Pass the module code to keep only lines that mention it. With the CLI: `dv sandbox logs -n 200`.

## 10. Versions

Ask: *"What versions of this module do we have?"* The agent calls `module_versions`, which lists the versions your workspace can see, which one is installed, and the install and update history. With the CLI: `dv modules versions <code>`, and `dv modules update <code>` moves your install to the newest version. See [Versions, drafts and history](article:b7f15cbd-b00f-42e3-a457-7a5b68642aeb).

## 11. Raise the version for every change

Versions can't be changed once deployed. Before deploying changed files, raise `version` in `module.json` (for example `0.1.0` to `0.2.0`). Changed code under an existing version is refused, and a version lower than the live one is refused. Deploying the exact same files again is harmless.

Tables only grow: new columns and tables are added, nothing is dropped or renamed, and existing data is reshaped with `data_migrations`. See [Module manifest (module.json) reference](article:42e987e5-382d-4d07-ab9b-13a60b831dee).

## 12. Submit to the Marketplace

If other companies could use the module, ask: *"Submit it to the Marketplace."* The agent should ask you first, then call `submit_to_marketplace`, or run `dv modules publish <code> -m "what changed"`. It submits the latest deployed version.

Before it will be accepted, the module needs:

- `"distribution": {"visibility": "marketplace", ...}` in `module.json`.
- QA procedures in `qa/procedures.json` (the `writing-qa-procedures` skill).
- At least one dataset for dashboards (the `registering-datasets` skill).

A refusal lists each blocking item with its fix: fix, raise the version, deploy and submit again. Data Visions staff test the module against its QA procedures and approve or reject it. Follow along with `marketplace_status` or `dv modules publish-status`.

## Good to know

- **Ask before deploying.** The agent should confirm with you before every deploy and Marketplace submission.
- **Module codes are permanent.** Pick one you can live with; changing it later means a new module.
- **Marketplace modules can't be checked out.** Their code belongs to their publisher.
- **For every tool and command in detail**, see [Connector tool reference](article:eb4fdce8-03a5-4b28-85f2-6bf0ab76a3f1) and [CLI command reference](article:9203acf3-a6ac-410b-8ada-73b8fa35654a).


Source: https://datavisions.ai/docs/developer-tools/build-a-module-with-a-coding-agent-start-to-finish
