Skip to content
Analytically.ai

Docs for TrueQuery 0.1.6View as Markdown

Install and first steps

TrueQuery needs uv (Python 3.11+). On Windows, the per-edit checks need Git for Windows.

Install for your agent#

Your agent
claude plugin marketplace add Analytically-ai/truequery
claude plugin install truequery@analytically

Open your project in Claude Code and run /truequery init, then try /truequery review models/ (or any folder of SQL). On Windows, the per-edit checks also need Git for Windows.

Or inside a Claude Code session:

/plugin marketplace add Analytically-ai/truequery
/plugin install truequery@analytically
/reload-plugins
/truequery init

/reload-plugins, or restarting Claude Code, loads the new plugin.

muse plugins marketplace add analytically https://github.com/Analytically-ai/truequery
muse plugins install truequery@analytically
muse plugins approve truequery

The last line approves the plugin's checks, once (Muse asks again only when they change). Then ask for data work in your own words, or load the skill with /skill truequery. The checks also cover SQL the agent writes from the shell (cat > q.sql, … | tee q.sql). If the skill can't find truequery on your PATH, install it with pip install truequery.

pip install truequery          # or: uv tool install truequery
truequery install --harness codex

This sets up the checks as the agent works (being verified live). Approve them once in Codex with /hooks. The full skill (the procedure, the commands and init) is coming next.

There's no skill in Codex yet, so there are no commands to run: the checks work as the agent edits.

pip install truequery          # or: uv tool install truequery
truequery detect path/to/code/       # findings
truequery review path/to/code/       # findings plus the receipt
uvx truequery detect path/to/code/   # or run it without installing

That installs truequery and the short alias tq.

pre-commit: add TrueQuery to .pre-commit-config.yaml (truequery checks staged .sql files; truequery-python checks .sql and .py):

repos:
  - repo: https://github.com/Analytically-ai/truequery
    rev: v0.1.6
    hooks:
      - id: truequery

GitHub Actions: run uses: Analytically-ai/truequery@v0.1.6 to check pull requests and write the receipt to the job summary. Full options and SARIF setup: docs/ci-and-pre-commit.md.

Keep it current with Stay up to date.

Run your first check#

Point the checker at a folder of SQL or Python. It prints the findings, then the receipt.

In Claude Code, run /truequery review models/. In Muse Code, ask for a review in your own words.

In a terminal, after pip install truequery:

truequery review models/

This is the end of a real run on samples/bad_orders.sql, a sample file of seven common SQL mistakes that ships with TrueQuery. ⋯ marks the findings, cut here:

$ truequery review samples/bad_orders.sql
⋯
TrueQuery receipt
Checked      1 SQL file · contracts for 0 of 3 tables
Found        5 errors · 2 warnings
Not checked  your data: TrueQuery reads files and never connects to your database
No contract  customers, orders, staging_orders

Read what it didn't check#

The receipt says what was checked and, just as plainly, what wasn't. Here that's your data: TrueQuery reads files and never connects to your database.

A file it couldn't parse is listed as not checked too, never as clean. So is SQL your program builds at run time, which can't be read from the file.

The receipt goes through it line by line.

Where to go next#