Insyte

Ask your database questions in natural language — locally, and safely.

Insyte connects to your database with read-only credentials and turns natural-language questions into safe analytics. Ask "what were total sales last month?" or "revenue by city" from a browser workspace, a terminal UI, or your own AI tool (Claude Code / Codex) — Insyte writes the SQL, runs it read-only, and shows the answer.

Two things are always true:

1. AI models never see your database credentials.
2. Nothing can bypass Insyte's SQL validation, row limits, PII masking, or audit log — a dangerous query is rejected, not executed.

What you can do

• Ask in natural language — "total order value last month", "orders by payment method", "monthly revenue trend", "what's the expected revenue this year?"
• Three ways to use it — a browser workspace (insyte studio), a terminal UI (insyte chat), or directly from Claude Code / Codex over MCP.
• Trends, breakdowns, opportunity segments, comparisons, and forecasts over metrics Insyte generates from your schema — with charts, tables, and the exact SQL on demand.
• Smart semantic aliases — during semantic generation, Insyte creates safe natural-language aliases from scanned tables, columns, metrics, and dimensions. "order count" can resolve to a real sales_order_count metric when the sales_orders table exists, but aliases only point at existing semantic objects and carry evidence.
• Profile-aware schema retrieval — guided setup safely profiles bounded samples and fingerprints the scanned schema. SQLite full-text search ranks structural metadata, while a deterministic semantic catalog ranks metrics, dimensions, aliases, and safe profile evidence. Only relevant known objects are offered to the AI resolver; its answer is still validated against the complete semantic layer.
• Investigation Mode Lite — ask broader questions like "why did total amount change?" or explicit comparisons like "Why did order count drop from February 2026 to March 2026?" and Studio runs a safe, multi-step investigation: trend, period-aware comparison, segment breakdown, freshness checks, and next questions. Relative questions such as "this week" use a daily trend and compare the elapsed window with the same elapsed window last week.
• Saved investigations — completed Studio investigations are saved locally with their timeline, report, original question, and linked analysis result. Reopen them from the Investigations workspace and export complete PDF reports.
• Task-aware model routing — intent resolution, investigation planning, and reports can use different local Claude/Codex backends. Explicit fallback is opt-in; deterministic behavior remains available for every task.
• Typed internal agents — planner, analyst, quality, report, and critic stages exchange validated models. Agents select approved operations and call AnalysisService; they never execute model-authored SQL or receive database credentials.
• Detailed reports (opt-in) — flip on "Detailed report" in Studio for an in-depth analyst write-up: executive summary, key insights, data-quality flags, root-cause reasoning, evidence/counter-evidence, best/expected/worst forecast, and prioritized recommendations, in a visual dashboard. Investigation questions can use the same analyst report skill over the grounded investigation bundle. See the privacy note below for what this shares.
• Interactive charts — charts include hover tooltips, readable date labels, expandable fullscreen views, and smooth trend lines for faster inspection.
• Conversation context — Studio remembers compact metric, dimension, period, and result context so follow-up questions like "same metric last month" resolve more reliably.
• Read-only and private — everything runs on your machine against your database; the raw connection URL never leaves your computer.

Detailed reports & your privacy

Everything above keeps your data on your machine. The one opt-in exception is the Detailed report: to write analyst commentary, Insyte sends the already-aggregated, PII-masked result of your query, or a grounded investigation bundle built from those aggregate results, to your local claude/codex CLI, which forwards it to that provider. The AI only writes prose — it never sees credentials, never authors SQL, and every chart is built by Insyte from real numbers. It's off by default, shows a one-time notice the first time you enable it, and can be turned off entirely with ai.detailed_reports: false in config.yaml.

Task routes are configured independently while retaining studio_backend compatibility:

ai:
  studio_backend: auto
  intent_backend: auto
  planner_backend: auto
  report_backend: auto
  fallback_backend: off
  detailed_reports: true

auto selects an installed local client. off uses the deterministic path. A failed explicit route tries another model only when fallback_backend is configured; otherwise it fails closed.

Smart aliases without hallucination

Insyte's semantic layer can understand obvious business phrasing without making up data. The semantic generator creates aliases such as order count -> sales_order_count only when the target metric already exists, and every alias stores evidence such as the metric name and expression. The parser uses high-confidence aliases after exact metric matching fails; low confidence or ambiguous aliases do not run silently.

AI-assisted enrichment is a bounded review step: it may propose a filtered metric only from an existing metric and exact, non-PII, low-cardinality profiled values. Proposals remain blocked until approved and cannot introduce tables, columns, joins, expressions, unobserved values, or SQL.

Install & set up

macOS app (no terminal or Python required for Insyte)

Download the latest Apple silicon DMG from GitHub Releases, drag Insyte to Applications, and open it. The app bundles the matching Insyte package and Python runtime, then opens the local Studio setup wizard. It does not run pip install on the user's computer. AI-powered questions use an already-installed Claude Code or Codex client; that client opens and owns its browser sign-in flow.

Release builds use the exact package version from the tagged source. Studio can check PyPI for a newer version and link to the latest release, but updates remain user-controlled.

Python package

Easiest — pipx installs Insyte in its own isolated environment (no virtual-env to manage):

pipx install insyte
insyte init          # asks for your read-only DB URL and which AI tool, then sets everything up

_{No pipx yet? brew install pipx (macOS) or python -m pip install --user pipx && pipx ensurepath, then reopen your terminal.}

Prefer plain pip? Install into a virtual environment:

python -m venv .venv && source .venv/bin/activate
pip install insyte
insyte init

You can now start with the browser instead:

insyte studio

When no project exists, Studio opens a local first-run wizard. Choose Claude, Codex, or the deterministic mode; paste a PostgreSQL URL; select schemas and SSL mode; and let Insyte test the read-only connection, scan, profile, generate metrics, and validate the semantic layer. The URL is submitted only to the local 127.0.0.1 process and is stored in the same protected 0600 project secret used by the CLI.

insyte init remains available for terminal-first and automated setup. It walks you through:

1. Enter your read-only database URL (stored once in a 0600 file — never in config, never logged, never sent to an AI).
2. Pick your AI tool — Claude Code, Codex, or none.
3. Insyte then connects, scans and profiles the schema, generates and validates metrics, proposes grounded derived metrics for review, creates concise schema-grounded starter questions, and wires up your AI tool — no scripts, no environment variables.

Then use it:

insyte studio        # browser workspace at http://127.0.0.1:3838
insyte chat          # terminal UI
insyte analyze total_amount --by city

AWS RDS and GCP Cloud SQL

The Studio wizard accepts standard password-based PostgreSQL URLs for Amazon RDS/Aurora PostgreSQL and Google Cloud SQL for PostgreSQL. The database must be reachable from the local computer through an allowlisted public endpoint, VPN, or an already-running proxy/tunnel. Use a dedicated PostgreSQL role with CONNECT, schema USAGE, and table SELECT privileges only.

AWS IAM tokens and automatic Google Cloud SQL Auth Proxy/IAM login are not static URLs and are planned as separate credential providers. BigQuery, Redshift, Athena, and Spanner are not PostgreSQL and are not supported by this connector.

Studio Settings also includes Check for updates. It compares the running version with PyPI and links to the latest GitHub release; it never installs or upgrades packages automatically.

Requirements: Python 3.11+, a PostgreSQL database, and — for natural-language questions — the claude or codex CLI (Studio also answers metric questions without one).

Recommended: a read-only database user

Insyte enforces read-only regardless, but a dedicated account is safest:

CREATE ROLE insyte_reader LOGIN PASSWORD '…';
GRANT CONNECT ON DATABASE your_db TO insyte_reader;
GRANT USAGE ON SCHEMA public TO insyte_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO insyte_reader;

Use it from Claude Code / Codex

insyte init already installs the Insyte MCP server into your chosen tool. Restart it, then ask questions in plain language — Claude/Codex call Insyte's safe tools; it validates, runs read-only, masks PII, and audits every query. (Re-run any time with insyte mcp install claude or insyte mcp install codex.)

Handy commands

Everything lives under ~/.insyte/projects/<name>/ (config, stored URL, scanned schema, metrics, aliases, conversations, saved investigations). The connection URL is read only when needed and never written to config.yaml.

When a question contains an undefined qualifier such as "positive", "failed", or "active", Insyte does not drop the qualifier and run the base metric. It may propose a derived metric using an exact non-PII profiled field and observed values, but that metric remains non-executable until you approve it from Studio's Metrics page or with insyte metrics approve <name>.

Feedback

Found a bug or have an idea? Please open an issue: https://github.com/insyte-ai/insyte/issues — feedback is very welcome.

Contributing

uv venv && uv pip install -e '.[dev]'
uv run ruff check src tests && uv run mypy src && uv run pytest -q

Security & license

See SECURITY.md for the read-only posture and how to report a vulnerability. Licensed under Apache-2.0 — see LICENSE.