Dex | Dex
Most deadly errors arise from obsolete assumptions.
Frank Herbert, Children of Dune
Dex
Dex lets your agent build your analytics.
Explore your data, build models and semantic layers, and keep them in sync as schemas change.
Works with databases, data warehouses, lakehouses, and SQL engine endpoints through supported connectors.
Built by Exmergo
Install
Any agent (run in your terminal):
npx skills add exmergo/dex
Claude Code (run these inside Claude Code, one at a time):
/plugin marketplace add exmergo/exmergo-agent-plugins
/plugin install dex@exmergo
Codex:
npx skills add exmergo/dex --agent codex
What you get
- Explore your database, data warehouse, or SQL endpoint. Find the tables that matter, understand their structure, and verify how they join. Get column profiles, personal-data flags, and an ER diagram.
- Transform your dbt project and semantic layer. Create models, tests, docs, and metrics as reviewable plans, then build and verify on a dev target.
- Maintain your models and metrics as sources change. Detect drift in schemas, volumes, grain, and metric definitions, with proposed fixes to review.
Your source data stays read-only. Builds run on a dev target, query costs are quoted before spend, and every project change is a diff you review. Works in Claude Code, Codex, or any agent that loads Agent Skills.
Dex needs
uvon yourPATH. No agent installs it for you. Runbrew install uvorpipx install uv, or see the uv installation docs for other platforms.uvsupplies Python and the engine. Use uv 0.13.4 or later (uv self update): earlier releases still trust the emSign CA roots withdrawn after their keys were compromised.
In Claude Code the skills appear as /dex:explore, /dex:transform, and /dex:maintain and trigger on matching intent. Update later with /plugin marketplace update exmergo. Codex also gets a native plugin, with no MCP server needed. Any other agent can be pointed at AGENTS.md.
Run Dex from your project directory, so it finds your .dex/config.yml and keeps its cache next to your project. Dex needs an agent with a local shell, so it does not run in claude.ai chat.
Why
Writing SQL is one part of analytics engineering. Your agent also needs to:
- understand the schema without starting from scratch every session,
- find the relevant tables among thousands,
- account for what a query costs,
- keep personal data out of its context,
- keep models and metric definitions coherent as their sources change.
Dex gives the agent a repeatable explore, transform, maintain loop, with guardrails enforced in the engine.
Quickstart
Initialize
If you want to use the python package exmergo-dex-core:
- Install it with
uv, with the extras you need (i.e. DuckDB)
uv tool install "exmergo-dex-core[duckdb]"
- Initialize a Dex project (creatively called "analytics")
dex init analytics
Demo
Try Dex in a demo experience with no existing database, no credentials, no cloud account, and no network once the package is installed:
uv tool install "exmergo-dex-core[duckdb]"
dex init analytics --mode demo
dex explore map
dex init analytics --mode demo creates the e-commerce DuckDB warehouse (dex_demo.duckdb, 7 tables, 29,512 rows), a dbt project under analytics/, repository-level Dex configuration, and onboarding documentation. Reruns preserve authored files. The lower-level dex demo command remains available for creating just the warehouse and config. The data comes from a pinned seed.
explore map maps all 7 tables, infers 5 joins, flags 6 columns as personal data, and reports 6 data-quality findings. Every command answers with one JSON envelope.
The demo is broken (on purpose!)
A first run that reports a clean bill of health doesn't teach us much, so the demo ships with real defects. Dig into them:
dex explore profile order_items products
dex explore relationships --verify
dex explore query "select email from customers"
- A broken grain. A batch was loaded twice, so
order_item_idis unique for only 92.9% of rows. - A key that mixes id schemes.
skuis90% numeric, 10% 32-character hexadecimal (md5-shaped). Cast it to a number and you silently drop 10% of products. - A join that looks right and is not.
web_events.customer_idshares a name with the CRM's key, but verification finds 100% of its values have no match. - A refusal. The query firewall will not put
customers.emailinto context.select count(distinct email) from customersruns, because a statistic is not a value.
How it works
The skills connect your agent to the exmergo-dex-core engine, which holds the logic and guardrails behind a small command contract. Your dbt project and semantic-layer definitions live in your repository as reviewable files. The .dex/ directory holds Dex's cache and snapshots.
Explore
Find the tables that matter, profile their columns, and verify joins before writing SQL. Answer ad-hoc questions through a query firewall that checks for personal data, read and query the semantic layer, and map relationships as a Mermaid ER diagram. Exploration is read-only and needs no dbt project.
Transform
Build and refactor dbt models from staging to marts, with tests, docs, and declared grain and population. Define semantic models and metrics over them, or work with a native semantic layer without a dbt project. Review each stored plan before applying it, then build and verify on a dev target.
Maintain
Compare database schemas and profiles, the dbt project, and the semantic layer with the last snapshot. See which models and metrics a change affects and review the proposed edits. maintain verify also checks a project as it stands, with no baseline needed.
Connectors
| Connector | Type | Self-hostable | Extra / --connector |
Cost guardrail | Connection details |
|---|---|---|---|---|---|
| Snowflake | Cloud warehouse | ❌ | snowflake |
Warehouse-seconds, with credits | connections.toml, SNOWFLAKE_* env, or a dbt profile |
| BigQuery | Cloud warehouse | ❌ | bigquery |
Bytes scanned | Application Default Credentials |
| Databricks | Lakehouse via SQL endpoint | ❌ | databricks |
Warehouse-seconds, with DBUs | databricks auth login, DATABRICKS_* env, or a dbt profile |
| Amazon Redshift | Cloud warehouse, Serverless-first | ❌ | redshift |
Compute-seconds, with RPU-hours | The AWS credential chain or REDSHIFT_* env |
| Postgres | Operational database | ✅ | postgres |
Database-seconds | pg_service.conf, DATABASE_URL, PG* env, or a dbt profileAlso works with Supabase, Neon, and more managed Postgres platforms |
| DuckDB | Embedded analytical | ✅ | duckdb |
Free and local | None, just a file path |
| ClickHouse | Analytical database | ✅ | clickhouse |
Compute-seconds on Cloud, database-seconds self-hosted | CLICKHOUSE_URL, CLICKHOUSE_* env, or a dbt profile |
| Trino | Federated query engine | ✅ | trino |
Cluster-seconds | TRINO_URL, TRINO_* env, or a dbt profileAlso works with: MySQL, SQL Server, MongoDB, and more databases through Trino catalogs |
Credentials are discovered and never enter the agent's context. Every scan is estimated, confirmed, and capped server-side, and settled spend is recorded in a local ledger ( cost controls). Self-hosted databases bill no dollars and are still gated, because an unbounded scan on a production Postgres primary is a real cost too.
Semantic layers
Choose the semantic layer independently of your database connector. Dex supports dbt semantic models and native Ossie, SLayer, or Cube files. Configure the choice in .dex/config.yml; Ossie, SLayer, and Cube need no dbt project.
| Semantic layer | Authorable | Hosted | Queryable | vendor / deployment |
Read through | Documentation |
|---|---|---|---|---|---|---|
| Apache Ossie (incubating) | ✅ | ❌ | ❌ | ossie / local |
Native documents in the repository, no dbt or MetricFlow in the path | Docs |
| dbt | ✅ | ✅ | ✅ | dbt / local or dbt_cloud |
MetricFlow locally, run through the Dex connector and its cost guard, or the hosted dbt Cloud Semantic Layer API | Docs |
| Databricks Metric Views | ✅ | 🚧 | 🚧 | databricks / local |
Metric View YAML files in the repository, read and authored statically with no workspace connection; nothing is deployed, and querying is not yet supported | Docs |
| Snowflake Semantic Views | ✅ | 🚧 | 🚧 | snowflake / local |
Semantic View YAML files in the repository, read and authored statically with no Snowflake connection; nothing is deployed, and querying is not yet supported | Docs |
| SLayer (by Motley) | ✅ | 🚧 | ✅ | slayer / local |
SLayer model files, validated by one pinned release; SLayer renders, Dex runs it under the cost guard | Docs |
| Cube | ✅ | 🚧 | ✅ | cube / local |
Plain YAML model files, read statically with no Node or Cube server; querying asks a running Cube server to render, Dex runs it under the cost guard | Docs |
Dex Semantics
Let your agent build analytics with 25% fewer errors, thanks to data that explains itself to your coding agent.
A join can keep running after the source changes underneath it, and quietly count every row twice. Dex Semantics keeps each model's meaning with the model, as code, so that kind of error is caught instead of shipped:
- Declare the rules. Every model your agent creates or changes carries a declaration: what one row is, which rows belong, how each number adds up, and the assumptions behind it. Dex drafts what it measured; the intent is yours.
- Check the results.
transform build --verifyholds the built data to the declaration: duplicate keys, rows the population excludes, a running total summed across time. - Keep the context. The declaration becomes dbt tests, is read back by the next agent session, and derives the semantic model for any layer above.
25% fewer failed tasks on ADE-bench with Claude Sonnet 5.5 (15 against 20 of 75).
See it on a real project
github-repo-analytics is a template that tracks GitHub traffic, stars, downloads and contributors for your open-source projects, free on GitHub Actions.
Every model and metric was built and is maintained with Dex. Its audit trail holds the raw envelopes, including the drift Dex blocked.
Use Dex from Python
The engine is a plain Python package, exmergo-dex-core:
pip install exmergo-dex-core # or: uv add exmergo-dex-core
Drive the same loop from Python instead of parsing CLI output:
from exmergo_dex_core import DexEngine
with DexEngine(connector="duckdb", path="shop.duckdb") as eng:
mapped = eng.map() # a DexCache, not a JSON blob
rows = eng.query("select status, count(*) from orders group by status")
print(mapped.relationship_count, rows.cells)
Every guarantee the CLI makes holds here, because it is the same code. An unconfirmed billed call raises ConfirmationRequiredError carrying the estimate.
Benchmarks
We run Dex on two public analytics-engineering benchmarks and commit every run's raw per-task results, including the ones that flatter us least.
| Benchmark | Setup | Result | Details |
|---|---|---|---|
| data-eng-bench (Snowflake, 103 tasks) | Dex + Claude Sonnet 5 | 57.3% resolved, 89.7% of assertions pass | README |
| ADE-bench (dbt Labs, 75 tasks) | Dex 1.17.4 + Claude Sonnet 5.5 | 80% resolved vs 73.3% without Dex; 25% fewer failures | README |
We believe that benchmarks are important, but not as important as user/agent experience.
Managing the Dex lifecycle
What Dex sends where
- On install,
uvdownloads the pinned engine (and a Python 3.11 to 3.14 if you have none, or if your newest is a 3.15, which Dex does not support yet) from PyPI or your configured index. - Your connected database, data warehouse, or SQL endpoint gets SELECT-only SQL from Dex, plus the dbt builds you confirm on a dev target, with credentials from your existing credential chain.
- dbt Cloud is contacted only if you enable the hosted semantic layer.
Feedback and bug reports
Found something wrong, or something Dex should do? Open an issue: bug reports and ideas are welcome, including ones your agent drafts for you. Run dex feedback for the environment to paste and links that prefill the bug report and feature request forms; nothing is sent. Security problems go to SECURITY.md, never a public issue.