# Install and first steps

Docs for TrueQuery 0.1.6. Install TrueQuery for Claude Code, Muse Code, Codex, or any terminal and CI, then run your first check.

TrueQuery needs [uv](https://docs.astral.sh/uv/) (Python 3.11+). On Windows, the per-edit checks need [Git for Windows](https://git-scm.com/download/win).

## Install for your agent

### Claude Code (Ready)

```bash
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](https://git-scm.com/download/win).

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 Code (Ready)

```bash
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`.

### Codex (Early access)

```bash
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.

### Any agent, terminal or CI (Ready)

```bash
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`):

```yaml
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`](https://analytically.ai/truequery/docs/pre-commit.md).

Keep it current with [Stay up to date](https://analytically.ai/truequery/docs/stay-up-to-date.md).

## 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`:

```bash
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:

```output
$ 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](https://analytically.ai/truequery/docs/receipt.md) goes through it line by line.

## Where to go next

- [Try it on the demo shop](https://analytically.ai/truequery/docs/try-the-demo.md), with a prompt for each role.
- [Set up your project](https://analytically.ai/truequery/docs/set-up.md): `/truequery init` and `DATA.md`.
- [What the checker finds and promises](https://analytically.ai/truequery/docs/checker.md), and [all 32 checks](https://analytically.ai/truequery/checks).
- [Run it in CI](https://analytically.ai/truequery/docs/pre-commit.md), with pre-commit or a GitHub Action.