██████╗   ██████╗  ██╗      ███████╗ ██╗  ██╗
 ██╔══██╗ ██╔═══██╗ ██║      ██╔════╝ ╚██╗██╔╝
 ██║  ██║ ██║   ██║ ██║      █████╗    ╚███╔╝
 ██║  ██║ ██║   ██║ ██║      ██╔══╝    ██╔██╗
 ██████╔╝ ╚██████╔╝ ███████╗ ███████╗ ██╔╝ ██╗
 ╚═════╝   ╚═════╝  ╚══════╝ ╚══════╝ ╚═╝  ╚═╝

Dolex turns your AI assistant into a data analyst you can trust on your own data.

A B2B data-analysis product that gives your AI assistant a rigorous analyst's discipline, working on your own files and handing back artifacts you keep.

Dolex connects to your data — a folder of CSV files, or a live PostgreSQL or MongoDB database — audits it, runs the analysis, and returns real results you own. It runs locally: point it at a folder of CSVs and they load as one joinable database, or connect a Postgres/MongoDB source and query it in place. It profiles every column, classifies what each one is, and builds a prioritized analysis plan with ready-to-run queries. Every answer traces back to an inspectable query, and the findings come back as artifacts you keep. Dolex ships as a published npm package with two front ends over one core: an MCP server any AI assistant can call, and a command-line tool your terminals, scripts, and pipelines run directly.

What you get

• Analysis on your own data. Point Dolex at a folder of CSV files — they become one database your assistant can join across — or connect a live PostgreSQL or MongoDB database and query it in place. Same tools, same analysis, whatever the source.
• Data you can stand behind. A built-in audit surfaces type traps, sentinel values, leaked and duplicate columns, and outliers before they reach a conclusion.
• Rigor on every result. Full column profiling and statistics back the analysis, and each finding traces to a query you can inspect.
• A real analysis plan. Dolex classifies your columns and produces a prioritized analysis plan with ready-to-run queries; derived columns persist across sessions.
• Artifacts you keep. Findings render across 43 chart types as self-contained HTML or PNG, with React components, a design system, and the queries behind every result.
• One analyst on call everywhere. The same core serves your chat assistant and your pipelines, with concurrent work running in its own lane.

Install

npm install -g @outsidedata/dolex

To update:

npm update -g @outsidedata/dolex

Optional — PNG export. Rendering charts to PNG (the --png flag and the MCP screenshot tool) needs Playwright, which is not installed by default. Enable it once with npm install playwright && npx playwright install chromium. Everything else — HTML charts, querying, analysis, the MCP data tools — works without it.

Claude Desktop

Add to your config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "dolex": {
      "command": "dolex"
    }
  }
}

Claude Code

claude mcp add dolex -- dolex

Any MCP Client

Point your client's server command at dolex. Launched by an MCP client over stdio, it runs the server. To start it explicitly — or to confirm it boots from a terminal — use the subcommand:

dolex mcp

Command Line

The same analysis engine, query layer, and 43 chart types are a CLI away — point it at a CSV and get a chart, an analysis plan, or a data-quality audit.

# Chart a CSV — the pattern matches the shape of the data
dolex visualize sales.csv -i "compare revenue by region"

# Query first, then chart; force a type and palette; render a PNG
# (PNG export is optional — enable it once with:
#    npm install playwright && npx playwright install chromium)
dolex visualize games.csv \
  --sql "SELECT genre, SUM(na_sales) sales FROM video_games_sales GROUP BY 1" \
  -i "sales by genre" --pattern lollipop --palette blueRed --png genre.png

# Refine the last chart — works across separate invocations
dolex refine spec-1a2b3c4d --sort desc --limit 10   # hash printed by visualize

# Explore without charting
dolex check diamonds.csv          # audit data quality + footguns before trusting it
dolex query diamonds.csv "SELECT cut, MEDIAN(price) FROM diamonds GROUP BY 1" --format json
dolex analyze diamonds.csv        # auto analysis plan with ready-to-run SQL
dolex describe diamonds.csv       # column types, roles, stats, sample rows
dolex patterns                    # browse all 43 chart types

# Persisted derived columns (survive across commands via a .dolex.json manifest)
dolex transform diamonds.csv --create price_per_carat --expr "price / carat"
dolex query     diamonds.csv "SELECT cut, AVG(price_per_carat) FROM diamonds GROUP BY 1"
dolex columns   diamonds.csv      # list source / derived / working columns

| Command | What it does | |---------|-------------| | visualize | Turn a CSV / source / inline JSON into a chart (HTML, optionally PNG) | | refine | Tweak a chart by its hash — sort, filter, palette, switch type, … | | query | Run SQL and print rows (table / json / csv / ndjson) | | analyze | Auto-generate an analysis plan with ready-to-run SQL | | describe | Profile columns: types, roles, stats, sample rows | | check | Audit for bad data & footguns (type traps, sentinels, duplicate/leaked columns…) | | transform | Add a persisted derived column (--create … --expr …) | | columns | List columns by layer (source / derived / working) | | drop | Remove derived/working columns | | patterns | List the 43 chart patterns, or show one in detail | | sources | Register & manage data sources — CSV, Postgres, MongoDB (shared with the MCP server) | | deps | Report which data sources & optional features are available in this environment | | mcp | Run the MCP stdio server |

Charts default to ~/.dolex/charts/; pipe-friendly via --stdout / --json. Full reference: docs/CLI.md.

Data Sources

Dolex works the same whether your data is files or a live database. Point it at:

• CSV — a single file or a whole folder, loaded as one joinable in-memory database (SQLite under the hood).
• PostgreSQL — a live database queried in place with real SQL; declared foreign keys are read straight from the schema.
• MongoDB — collections profiled as tables and queried with aggregation pipelines.

The Postgres and MongoDB drivers are optional — the base install stays lean and requires neither. Run dolex deps (or ask the assistant for capabilities) to see which sources are ready here and the exact one-line command to enable anything missing, so you get an install hint instead of a crash. Credentials stay out of the registry file: a Postgres password is read from an env var at connect time, and a source can be registered even while its database is down, then health-checked with dolex sources test / the test_source tool once it is up.

# CSV stays the zero-config default
dolex sources add sales ./data/sales.csv

# Live databases — driver installed on demand, secret via env var
dolex sources add warehouse --type postgres --host db.internal --database analytics --user reader --password-env PGPASSWORD
dolex sources add events    --type mongodb  --host localhost --port 27017 --database app
dolex sources test warehouse       # confirm it's reachable with its saved credentials

The Query Engine

Point your assistant at a folder of CSV files — or a live Postgres/MongoDB database — and start asking questions. Dolex profiles your data — column types, distributions, cardinality, sample values — giving your assistant everything it needs to answer.

The built-in query language covers the analysis your assistant runs:

Aggregations: sum, avg, min, max, count, count_distinct, median, stddev, p25, p75, percentile

Window functions: lag, lead, rank, dense_rank, row_number, running_sum, running_avg, pct_of_total — with partition and order control

Time bucketing: group by day, week, month, quarter, year — automatic date parsing

Joins: inner and left joins across tables within the same source, with dot-notation field references and ambiguity detection

Filters: before aggregation (filter) and after (having), with operators =, !=, >, >=, <, <=, in, not_in, between, like, is_null, is_not_null

Every query is validated before execution — field names are checked against the schema with fuzzy "did you mean?" suggestions for typos.

43 Patterns

| Category | What they're for | |----------|-----------------| | Comparison (9) | Bar, Diverging Bar, Slope Chart, Connected Dot Plot, Bump Chart, Lollipop, Bullet, Grouped Bar, Waterfall | | Distribution (7) | Histogram, Beeswarm, Violin, Ridgeline, Strip Plot, Box Plot, Density Plot | | Composition (9) | Stacked Bar, Waffle, Treemap, Sunburst, Circle Pack, Metric, Donut, Marimekko, Icicle | | Time (7) | Line, Area, Small Multiples, Sparkline Grid, Calendar Heatmap, Stream Graph, Horizon Chart | | Relationship (5) | Scatter, Connected Scatter, Parallel Coordinates, Radar, Heatmap | | Flow (4) | Sankey, Alluvial, Chord, Funnel | | Geo (2) | Choropleth, Proportional Symbol — 33 offline maps (world, US, continents, 17 countries) |

Tools

| Tool | What it does | |------|-------------| | load_source | Load a data source — CSV file/directory, PostgreSQL, or MongoDB | | list_data | List loaded datasets | | remove_data | Remove a loaded dataset | | capabilities | Report which source types & optional drivers are available in this environment | | test_source | Health-check a registered Postgres/Mongo source (reachable? credentials valid?) | | describe_data | Profile columns, stats, sample rows | | analyze_data | Auto-generate an analysis plan | | query_data | Run queries (SQL for CSV/Postgres; aggregation pipelines for MongoDB) | | visualize | Data → ranked chart recommendations (inline, cached, or source + query) | | refine_visualization | Iterate on a chart | | transform_data | Create derived columns with expressions | | promote_columns | Persist working columns to disk | | list_transforms | List columns by layer (source/derived/working) | | drop_columns | Drop derived or working columns | | clean_column | Fix one column with a Python clean(value) — parse dates, null sentinels, canonicalize categories; preview then non-destructive apply (requires python3) | | list_patterns | Browse all 43 patterns | | export_html | Get raw HTML | | screenshot | Render to PNG | | server_status | Inspect server state | | clear_cache | Reset |

License

MIT