DuckLocal

Let AI agents query local data with SQL

Give Claude Code, Codex, Cursor and other coding agents a headless DuckDB workflow for CSV, Parquet, JSON and DuckDB data. No GUI automation, database server or custom API required.

Download DuckLocal Install the agent skill

The CLI prints JSON by default and uses explicit exit codes for arguments, SQL and I/O failures.

Discover first, query second

The official workflow keeps an agent from guessing column names or treating a partial preview as the whole dataset.

  1. Map the schema

    Run ducklocal schema ./data/ to get relations, query-ready FROM expressions, columns and types. Large catalogs return a summary with hints for drilling down.

  2. Preview within bounds

    Use one SQL statement and a small --limit to inspect representative rows. Check the command’s exit status and the JSON truncated field.

  3. Compute the answer in SQL

    Run filters, joins and aggregates in DuckDB rather than summing a truncated preview in the agent context. Return only the evidence the answer needs.

One command, one SQL statement

Each invocation creates a dedicated DuckDB connection, validates that the input contains exactly one statement and writes a machine-readable result to stdout. Errors are JSON on stderr with a nonzero exit code.

Read the query contract

Terminal
$ ducklocal query --sql \
  "SELECT channel, round(sum(revenue), 2) AS revenue
   FROM 'sales.csv'
   GROUP BY channel
   ORDER BY revenue DESC"

{"columns":[...],
 "rows":[["Mobile app",290549.76],...],
 "row_count":4,
 "truncated":false,
 "elapsed_ms":14}

A small interface with explicit contracts

ducklocal schema ./data/

Discover relations

List files, tables, views and their columns before writing SQL.

ducklocal schema sales.csv --stats

Profile one relation

Get exact nulls, distinct values, ranges, medians and date coverage.

ducklocal query --sql "…"

Run one statement

Receive typed JSON by default, or a Markdown table with --format md.

ducklocal open --title "…" --run --sql "…"

Hand work to a person

Open a query in the desktop app when the result needs review or further exploration.

Output that tells the agent when it is incomplete

The default return limit is 1,000 rows, with an additional 2,000,000-cell budget. DuckLocal reads one extra row to determine whether the response was cut short and exposes that as truncated.

Queries such as GROUP BY, ORDER BY and aggregates still compute over the full input before returning their bounded result.

  • Typed columns and rows in a stable JSON envelope
  • Explicit row_count, truncated and elapsed_ms
  • Exit 2 for invalid arguments; exit 1 for execution failures
  • JSON errors on stderr, leaving stdout empty
  • Markdown output for human-readable reports

Teach the workflow, not just the command

The open-source DuckLocal skill teaches an agent to inspect the schema, preview a bounded sample, aggregate in SQL, verify truncation and answer from returned values. Install it for Claude Code from the app, or copy the same brief into another coding agent.

Install and inspect the skill

Read: What Claude Dashboards taught me about DuckLocal →

A local CLI—not a hidden cloud service or sandbox

DuckLocal does not upload local files to a DuckLocal service, but it does not pretend arbitrary SQL is harmless. Read-only database mode is not a filesystem or network sandbox: SQL such as COPY, extension installation or explicit external access can have side effects.

  • Authorize output paths, overwrites and database mutations
  • Authorize extension installation and external access
  • Inspect a destination before retrying a failed write
  • Use --read-write only for an intentional database change
  • Check ducklocal --help before relying on a command

Need the visual workflow instead? See local data analysis in the desktop app →

AI agent SQL questions

How does an AI agent query local data with DuckLocal?
The agent runs ducklocal schema to discover relations and columns, then ducklocal query with one SQL statement. The command returns structured JSON by default without opening the desktop window or starting a server.
Does the CLI return complete data by default?
No. Query output is deliberately bounded: the default row limit is 1,000 and a 2,000,000-cell budget also applies. The JSON response reports whether it was truncated. Full aggregates should be computed inside SQL.
Can DuckLocal run SQL scripts for an agent?
Each ducklocal query invocation accepts exactly one SQL statement. Multi-statement scripts are rejected rather than partially executed, which makes each tool call easier to inspect.
Is DuckLocal an MCP server or security sandbox?
No. DuckLocal provides a command-line interface and an optional agent skill, not an MCP server or a security sandbox. Potential writes, extension installation and external access still require normal authorization.

Give your agent a schema-first SQL workflow

Install DuckLocal, put the command on your PATH and start by asking what is actually in the data.

Download DuckLocal Read the CLI guide