DuckCode

What is ZLens?

ZLens is a local, open-source workbench for governed analytics. It works on top of your dbt project, or straight on your database's own tables. It turns the analytics people build (queries, notebooks, dashboards and AI answers) into files you review in git, and it tells you how far to trust each answer.

Watch the 90-second film for the whole idea.

When someone asks a question, ZLens tries the most trusted source first and labels what it used:

Label	Answered from	Means
● Certified	a certified saved query	Ran a saved query a person reviewed and certified, exactly as certified.
◐ From Metrics	your semantic layer	Built from approved metrics and dimensions. Not certified.
○ Needs review	SQL written by AI	Grounded in your schema and checked before it runs, then saved as a draft saved query until someone certifies it.

If none of these can answer safely, Ask refuses and says why. It never dresses an unreviewed number up as a trusted one.

• dbt stays the source of truth. ZLens reads your manifest, semantic models and profiles; it does not replace dbt. No dbt? ZLens reads your database's tables, keys and comments and drafts the joins for you to certify.
• Everything is a file. Saved queries (.dql block files), notebooks (.dqlnb) and Apps live in your repo, so they are diffed, reviewed and versioned like code.
• Works with your coding agent. A built-in MCP server gives Claude Code, Codex, Cursor and Claude Desktop the same certified-first answers and labels.
• Runs on your terms. Use a Claude or ChatGPT subscription, an API key (Anthropic, OpenAI, Gemini or any OpenAI-compatible endpoint), or a local model through Ollama. No ZLens account or hosted service, and no usage telemetry.

Try it in one click

See ZLens working on the Jaffle Shop sample, with nothing to install.

In your browser:

Click the button, then Create codespace. In about a minute ZLens opens in a panel inside the codespace, and the terminal prints a link that opens it in its own tab: the certified saved queries, the Jaffle Growth Review App, lineage and notebooks. Nothing opened? Click Ports, then the globe next to ZLens (3474). It uses your GitHub account's free Codespaces hours; stop it at github.com/codespaces when you're done.

With Docker:

docker run --rm -p 127.0.0.1:3474:3474 -p 127.0.0.1:54545:54545 -p 127.0.0.1:1455:1455 ghcr.io/duckcode-ai/zlens-demo

Open the link it prints. It runs on your machine and keeps nothing after you stop it (Ctrl+C). Ports 54545 and 1455 let Sign in with Claude and Sign in with ChatGPT finish inside the container.

Either way, Ask needs an AI model: add one in Settings → AI provider. To use your own data, follow the Quickstart.

Quickstart

Run ZLens on the Jaffle Shop sample dbt project. It takes about ten minutes and needs Node.js 20, 22 or 24 (24 LTS recommended), Python 3.9 to 3.14 and git. ./setup.sh picks a supported Python for you. No warehouse account is needed. Node 25 and 26 are not supported yet: ZLens's DuckDB driver has no prebuilt binary for them.

1. Get the sample and set it up

The sample is the Jaffle Shop dbt project on DuckDB, already set up as a ZLens workspace. Clone it and run its setup script:

git clone https://github.com/duckcode-ai/jaffle-shop-duckdb.git
cd jaffle-shop-duckdb
./setup.sh

./setup.sh builds the sample's DuckDB database with dbt, installs ZLens and the DuckDB driver into this folder, and imports the dbt project. It ends with Setup complete. and is safe to run again.

Build the database:

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/dbt deps --profiles-dir .
.venv/bin/dbt seed --profiles-dir .
.venv/bin/dbt build --profiles-dir . --exclude resource_type:seed

Install ZLens and import the dbt project:

npm install
npm run sync

You don't need to install the DuckDB driver: npm run notebook installs the active connection's driver the first time it starts.

[!NOTE] npm 12 runs a dependency's install script only when package.json lists it in allowScripts. The sample already allows better-sqlite3, the SQLite library ZLens keeps its index in, and ZLens allows and rebuilds the DuckDB driver in .dql/connectors itself. If ZLens says it could not load better-sqlite3 (a folder installed before the sample had the entry), run npm install-scripts approve better-sqlite3 then npm rebuild better-sqlite3. See npm 12 and install scripts.

[!NOTE] Do not run create-zlens-app inside the sample: it creates a second, empty workspace in dql/.

2. Open the workbench

npm run notebook

The terminal prints Notebook ready: http://127.0.0.1:3474 and your browser opens it.

3. Finish Guided Setup and run a query

Guided Setup walks you through four steps: Open an existing ZLens project (already selected, click Continue to credentials), the sample's DuckDB connection (already configured and tested), an optional AI provider (Skip AI for now), then Finish setup · Build an App. Then open Notebooks → New Notebook, click Create DQL query → Switch to SQL cell, and run this with Shift+Enter:

select customer_name, count_lifetime_orders, lifetime_spend
from dev.customers
order by lifetime_spend desc
limit 10

Next: ask a question in plain English, keep the query as a saved query and certify it, or add ZLens to your own dbt project. The full walkthrough is the Quickstart guide.

No dbt? Start from your database: connect it, choose schemas, and ZLens drafts the models for you to certify.

npm install in a ZLens project (the sample, or one made with create-zlens-app) installs the CLI into that project, so npm run … and npx zlens … use the version that project was tested with. To have a zlens command everywhere:

npm i -g @zlens/cli --allow-scripts=better-sqlite3   # install or upgrade (npm 12 needs the flag)
zlens --version
cd your-dbt-repo && zlens init ./dql

Install only the driver your warehouse needs, into the project:

Database	Install before running queries
Databricks SQL	nothing (built in, over HTTPS)
DuckDB, or local CSV / Parquet / JSON files	npm install --prefix .dql/connectors duckdb
Snowflake	npm install --prefix .dql/connectors snowflake-sdk

The notebook's Connections page can install DuckDB or Snowflake for you. See Install, Connect a database, Connectors and Troubleshooting. Coming from the dql command and @duckcodeailabs/dql-cli? Install @zlens/cli; the install guide covers the switch.

Video tutorials

Short videos (about a minute each) on the ZLens YouTube channel. New here? Watch Start here, then Quick Start. The Video tutorials page in the docs lists every video next to its steps.

Playlist	What it covers
Start here	The whole idea in 90 seconds: certified answers, AI answers you can review, refusals instead of guesses.
Quick Start	Install, Guided Setup, your first question with a trust label, then your own data, with or without dbt.
Notebooks	SQL, charts, inputs and AI in one file you share, review in git and save as a saved query.
Blocks and certification	Saved queries your team can trust: import your SQL, add tests, then certify, change or retire.
Ask and trust	How Ask picks a source, what each label means, and when it refuses.
Semantic layer	Define a metric once so every answer computes it the same way, and certify how tables join. (These videos use the older label "Governed"; it is now "From Metrics".)
Lineage	Trace a number to its source, and see what a change will break before you make it.
Share and review with git	Review data work like code: see what changed, share a review branch and pull request, get updates.
Your AI agent + ZLens	Use ZLens from Claude Code, Claude Desktop, Codex and Cursor over MCP.
Evals and CI

Features

Ask, with a trust label and the receipts

Ask a question in plain English. The answer opens with its trust label, the saved query or metrics it came from and their owner. How it was answered shows every step: the certified saved queries it checked, the semantic layer, the checks before running, and the exact DQL and SQL that ran.

When no certified saved query or metric fits, AI writes the SQL from your schema. ZLens checks it before it runs, labels the answer AI-generated, and saves it as a draft saved query for someone to review. It never certifies itself.

Ask a question · How Ask answered · Answers that need review

Saved queries: save is a draft, certify is a person

A saved query is a named, reusable query with an owner, a description, tests and a chart. Save a notebook cell with Save as saved query, and it is a draft. Certify runs the saved query and its checks; only if they pass does it become Certified, with a receipt of who certified it, when, and under which rules.

Saved queries · Save and certify

Notebooks

Explore with SQL, DQL, Ask AI, note and input cells against your warehouse. Results show with filters, pivots, charts and CSV or JSON export. The notebook is a .dqlnb file; results stay out of git.

Work in a notebook

Apps and dashboards

Build Apps from saved queries for the people who read the numbers. Every tile carries its trust label and a receipt, and the page says how much of it is certified. Ask about an App and the answer reads that page's own results and filters, and takes the trust of the weakest tile it read.

Read an App · Ask about an App

Lineage, from your tables to the App

Trace any saved query, App or notebook end to end: your warehouse tables (and, if you use dbt, the sources and models behind them), business terms, the saved query, its chart, the dashboard page and the App. Lineage is built from your synced warehouse catalog or dbt manifest plus your ZLens files, in the workbench or with zlens lineage.

Lineage

AI agents over MCP

Point your coding agent at the project and it answers data questions the way Ask does: certified saved queries first, the same trust labels, AI-written SQL kept as a draft for review.

$ npm exec -- zlens connect claude-code

  ZLens agent connection setup
    Project: /path/to/jaffle-shop-duckdb

  ✓ Claude Code
    Project .mcp.json and CLAUDE.md now point Claude Code at ZLens.
    Next: Open Claude Code from this project and run /mcp to confirm the dql server is loaded.

  Verify before asking an agent: zlens mcp test

zlens connect also supports codex, cursor, claude-desktop and all. Keep npm run notebook running while the agent works: it runs the queries.

Connect your AI agent · MCP tools

How it works

1. Sync. zlens sync dbt reads your dbt manifest, semantic models and warehouse shape into a local index. Without dbt, zlens sync warehouse reads the schemas you choose: tables, columns, keys and comments.
2. Certify. Saved queries are reviewed queries with an owner and tests. Certifying records who vouched for them.
3. Compile. zlens compile writes dql-manifest.json: every saved query, metric, notebook and App, with lineage and trust.
4. Serve. Apps, notebooks, Ask, your agent over MCP and zlens eval in CI all use the same certified saved queries instead of each inventing its own SQL.

DQL is the language saved queries are written in: each is a block in a .dql file. See Concepts, the DQL language and the architecture overview.

Packages

ZLens ships as 18 npm packages. Most people only need create-zlens-app or @zlens/cli.

Package	What it is
@zlens/cli	The zlens command: workbench, sync, compile, certify, lineage, Ask and the MCP server
create-zlens-app	Scaffolds a ZLens project, next to your dbt project or for a database alone
@zlens/core	DQL language core: lexer, parser, AST and semantic analysis
@zlens/dql-compiler	DQL compiler: IR lowering, Vega-Lite generation, HTML and CSS output
@zlens/runtime	Browser runtime: data fetching, Vega rendering, hot reload
@zlens/project	Project and block registry: block metadata, versions, sync and storage
@zlens/governance	Block testing, certification, cost estimation and access policies
@zlens/connectors	Connectors for local files, SQL warehouses and lakehouse engines
@zlens/notebook	Notebook document model and execution helpers

Contributing

Contributions are welcome. Start with CONTRIBUTING.md and the repository layout; the roadmap shows what is planned. Please follow the code of conduct.

Community and support

• Questions and help: ask in GitHub Discussions → Q&A. Not sure whether it's a bug? Ask there first.
• Ideas and feature suggestions: Discussions → Ideas.
• Show what you built: Discussions → Show and tell.
• Reproducible bugs and well-defined feature requests: open an issue.
• Release news: Announcements and Releases.
• Video tutorials: ZLens on YouTube.
• Security issues: follow SECURITY.md ([email protected]); do not open a public issue.

SUPPORT.md explains what to include when you ask and how we triage.

License

ZLens is licensed under the Apache License 2.0; see also NOTICE and THIRD_PARTY_NOTICES.md.

create-dql-app, @duckcodeailabs/dql-openlineage, @duckcodeailabs/dql-plugin-api and @duckcodeailabs/dql-telemetry were published as MIT up to and including 1.17.2; every later release is Apache-2.0. Versions already on npm keep the licence they were published under.