Important Notice

🚧 This project is under active development and not yet suitable for production use. Expect breaking changes, incomplete features, and evolving APIs.

Qwery: The Vision

Qwery is an AI data analyst that lives in your terminal. Ask questions in plain language; Qwery connects to your datasources, generates the SQL, runs it locally, and answers, without you ever leaving the keyboard.

It pairs two agents (a DataAgent for analysis and a CodingAgent for building scripts and apps) behind a single TUI.

Privacy by design

Row-level data never leaves your machine and is never sent to the LLM. Queries run in a local query engine; the model only ever sees schemas, aggregate scalars, and locally-rendered output. Destructive operations are protected by GFS ("git for databases"): the agent can branch and snapshot a database before touching it.

🌟 Features

• Natural-language querying: ask in plain language, get SQL automatically.
• Privacy-preserving: a local query engine keeps row data on your machine; only schemas/aggregates reach the LLM.
• Two agents: a DataAgent (analysis) and a CodingAgent (build/edit scripts and apps).
• GFS safety net: branch/commit/time-travel a database before destructive operations.
• Many datasources via extensions: PostgreSQL, MySQL, ClickHouse, DuckDB, CSV (local & online), Parquet, JSON, Google Sheets, S3, Excel (.xlsx).
• Bring your own model: configure any provider in-app via /models (Ollama local & cloud, Azure OpenAI, AWS Bedrock, and any OpenAI-compatible endpoint).
• Extensible: an extension SDK for custom datasources.

🚀 Quick Start

Install (recommended)

curl -fsSL https://raw.githubusercontent.com/Guepard-Corp/qwery-core/main/install | bash

This installs qwery (and the GFS engine) under ~/.qwery and adds it to your PATH. Then just run:

qwery

Once in the TUI, press /models to connect a provider. No API keys live in environment variables; provider configuration is stored under ~/.qwery.

Try it for free with Ollama: install Ollama, pull a tool-capable model (e.g. ollama pull qwen3-coder:30b), then in /models pick Ollama (local) and point it at http://localhost:11434/v1.

Run from source

Prerequisites: Bun >= 1.3.

git clone https://github.com/Guepard-Corp/qwery-core.git
cd qwery-core
bun install
bun start        # launch the TUI (use `bun dev` for --watch)

🛠️ Development

Monorepo structure

A Bun + Turborepo monorepo with a hexagonal architecture (see AGENTS.md):

• apps/cli: the Ink TUI (primary adapter)
• apps/e2e: end-to-end tests driving the real TUI
• evals/: real-model evaluation suite (NL→SQL correctness, etc.)
• packages/domain: entities, value objects, and ports (no I/O)
• packages/application: use cases orchestrating the domain
• packages/agent-factory-sdk: the agent loop, tools, and compaction
• packages/adapters/*: compute-duckdb, llm-aisdk, persistence-sqlite, model-catalog-http, branching-gfs, semantic-inprocess
• packages/extension-sdk + packages/extensions/*: datasource extensions
• tooling/: dependency-cruiser, privacy and coverage checks

Commands

bun start                 # launch the TUI
bun dev                   # launch with --watch

bun run lint              # Biome lint + format check (bun run lint:fix to apply)
bun run typecheck         # tsc -b
bun test                  # unit + component tests (bun:test)
bun run check:arch        # hexagonal boundaries (dependency-cruiser)
bun run check:privacy     # privacy invariant (no row data crosses the LLM line)
bun run coverage          # test coverage + ADR #16 tiered gate
bun run check:all         # lint + typecheck + arch + privacy + coverage

cd apps/e2e && bun test   # TUI end-to-end tests
cd evals && bun run evals # real-model evals (defaults to a local Ollama; skips if none)

Code quality standards

• TypeScript: strict typing, no any.
• Lint & format: Biome.
• Architecture: hexagonal boundaries enforced by dependency-cruiser.
• Tests: bun:test for unit/component, apps/e2e for end-to-end, evals/ for real-model checks.

Run bun run check:all before committing.

📚 Documentation

• Contributing Guide
• Agent & contributor guidelines
• E2E test plan

🤝 Contributing

We welcome contributions! Check out our Contributing Guide to get started.

Before submitting

1. Run bun run check:all to ensure all quality checks pass.
2. Follow our TypeScript guidelines.
3. Write tests for new features (a change without tests is incomplete).
4. Update documentation as needed.

Resources

• Review good first issues
• Read our Code of Conduct
• Check AGENTS.md for development guidelines
• Join our Discord community

💬 Join the Qwery Community

• Discord: Join our Discord for discussions and support
• GitHub Issues: Report bugs and request features
• YouTube: Watch demos and tutorials

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

🙏 Thank You

We're grateful to the open source community. See our Thank You page for acknowledgments.