Agami

agami-core is the trust layer between an AI agent and your database — a governed, self-improving semantic model that enforces correct joins, signed-off metric definitions, and a full audit receipt on every answer. Same question, same answer, every time. It builds itself from your live schema, messy or clean. The rules live in the model, not the prompt.

Real enterprise schemas have thousands of tables, mostly undocumented, with columns named col_47 and three definitions of "revenue". That's the problem this solves.

Get started in 2 minutes

In the Claude Code CLI:

/plugin marketplace add AgamiAI/agami-core
/plugin install agami-core@agami
/agami-connect sample          # zero setup: no database, no credentials
who are the top 5 customers by total spend?

In VS Code or Cursor, the two /plugin … commands above don't work from the chat input — type /plugin to open the Manage Plugins dialog and add the marketplace + install the plugin there instead (see Install). The /agami-connect line and everything after it work the same everywhere.

That last line returns a governed answer with a receipt (the exact SQL, the joins used, the model version) — and the governance runs before the query, so the kind of silent join mistake an ungoverned agent would hand back as a confident wrong number never reaches you. Two ways to go from here:

• 🧪 No database? The commands above answer from a built-in sample — nothing leaves your machine.
• 🗄️ Have a database? Run /agami-connect to introspect it into a governed semantic model, then just ask questions.

Each path is walked through in full below (Quickstart · Install).

What you get

• ✅ Governed answers, not guesses — every join is FK-derived or human-approved; every metric is signed off (name + role) before the runtime trusts it.
• 🧾 A receipt on every answer — the literal SQL, the tables touched, the relationships used, and the model version it pinned. Reproducible, auditable.
• 🔒 Local and private — runs inside Claude Code via Bash/Read/Write. Credentials, schema, and results never touch a server we operate.
• 🧩 A portable semantic model — plain YAML you own and can keep in git (subject areas, tables, entities, metrics, relationships). No lock-in.
• 📋 Built the way your warehouse's owners describe it — when the joins aren't declared (a star schema of views, keys named for their role), fill in a model spec workbook and the model is built exactly as it says.
• 🎯 Proof it still answers correctly — keep a golden dataset of questions with agreed answers, and re-score the model against it whenever it changes.
• 🗄️ Works with your database — Postgres · Supabase · Redshift · MySQL · Snowflake · BigQuery · SQL Server · Oracle · Databricks · Trino · DuckDB · SQLite.
• 🛠️ Zero infra to start — no backend, no proxy. If you have a DB CLI you have everything; an optional local MCP server lets Claude Desktop use the same model.
• 👥 Shareable with your team (early access — in testing) — self-host one governed server that your whole team and business users query from their own Claude over a URL, still zero-egress. The team layer is newer than the local path; we're validating it with early users.

Quickstart (under 5 minutes)

Fastest path — the built-in sample (no database, no credentials)

agami ships with Acme Store, a small local SQLite dataset (commerce + subscriptions) and a ready-made, signed-off semantic model. You get a governed answer — with a full receipt — in under a minute, and nothing leaves your machine.

# 1. Install the plugin (see Install below for the per-host steps).

# 2. Try the sample — no connection needed:
/agami-connect sample      # or just say "I don't have a database" / "try the sample"

# 3. Ask a question — see governance ENFORCED:
who are the top 5 customers by total spend?

# 4. Now watch the model get BUILT — see governance MADE:
/agami-connect reintrospect

Step 3 is where the governance fires. The sample question is deliberately one an ungoverned agent gets confidently wrong — a multi-table join where a naive agent silently returns a bad number. agami's pre-flight catches it and returns the correct answer with a join receipt — the trust layer, enforced on your very first query.

Step 4 is the real point. Natural-language querying is everywhere; what's rare is where the trust comes from. reintrospect re-derives the sample's model from the live schema — introspect → infer + confidence-score every join → gate metric sign-off → re-validate examples — so you watch the governed model take shape rather than just consuming it. To see it built from a blank slate (full LLM enrichment, descriptions and all), run /agami-connect sample and pick "build the model from scratch so I can see it work" the first time. Either way it takes a few minutes — it's the demo of how the receipts you saw in step 3 are earned. Full flow: docs/usage.md.

Your own database

Connecting your database is a short back-and-forth with agami — you fill in one template, and it handles the rest:

1. Start setup. Run /agami-connect (or just say "connect to my database"). agami asks which database you use, has you name the connection, and writes a credentials template for you to fill in.
2. Fill in the template. Open the file agami points you to, add your connection details, and save it — leave the filename as-is. agami only ever runs read-only queries, so a read-only database user is all it needs; ask agami for "the read-only grant" and it gives you the exact SQL to create one.
3. Say "introspect my database" (or just "continue"). agami takes it from there: it locks the file down for you (no manual chmod), reads your schema, builds the semantic model, and seeds a few validated example queries. You don't move or rename anything.
4. Ask a question — "how many orders did we ship last month?"

That's the whole setup. Along the way agami scores its confidence in every join and entity, auto-approves the clear ones (real foreign keys, well-named columns), and asks you to sign off the judgment calls. Full walkthrough: docs/usage.md. Connection details for each database: docs/credentials.md.

Joins not declared in the database? Many warehouses are views with no foreign keys, where ship_to_customer_key joins the customer table only by convention. Introspection can't see those joins, so describe them instead: fill in the model spec workbook — subject areas, which area owns each table, the joins (including condition joins such as current_flag = 'Y'), metrics, sensitive columns and rules — and attach it when /agami-connect asks for context. After introspection reads the listed tables, a dry run checks the whole workbook against them, and the spec replaces the introspected model only if it all validates — built exactly as it describes. Format: model-spec-format.md (early: the format may still change).

Databases supported

agami runs your SQL locally, with whatever's already on your machine — a native database CLI, the DuckDB universal binary, or a Python driver — picking the best option available. No agami-operated server ever sees your data.

Database	How agami runs the SQL
PostgreSQL · Supabase	psql CLI · DuckDB · psycopg2
Redshift	psql · psycopg2 (speaks the Postgres wire protocol)
MySQL / MariaDB	mysql CLI · DuckDB · pymysql
Snowflake	snowsql CLI · snowflake-connector-python
BigQuery	bq CLI · google-cloud-bigquery
SQL Server / Azure SQL	pymssql
Oracle	python-oracledb (thin mode — no client libs)
Databricks	databricks-sql-connector
Trino / Presto	trino
DuckDB	duckdb binary or module
SQLite	sqlite3 (Python stdlib — nothing to install)

agami picks the first method available for your database: a native CLI if one's on your PATH (nothing to pip install), then the DuckDB binary where it applies (Postgres · MySQL · SQLite), then the Python driver. Per-database connection fields and the read-only-grant SQL for every dialect are in docs/credentials.md. A read-only Postgres role still sees the primary and foreign keys (read from pg_constraint), and Redshift's late-binding views introspect with their columns.

Install

Platform note. Validated on macOS and Linux. On Windows the skills need Git for Windows (Claude Code uses Git Bash for its Bash tool). As of 0.9.11 the Python side works on Windows — UTF-8 throughout, correct query results, the Microsoft Store Python and Claude Desktop builds — but some skill instructions still assume macOS/Linux commands, and there's no Windows CI run yet (#362). The optional local MCP server is pure-stdlib Python and is cross-platform.

The same plugin works across Claude Code CLI, VS Code, and Cursor.

Claude Code CLI — in the Claude Code prompt:

/plugin marketplace add AgamiAI/agami-core
/plugin install agami-core@agami

Verify with /plugin list → you should see agami-core@agami installed.

VS Code / Cursor — the slash-command install form above is CLI-only; in the extension you install through the UI. Install the Claude Code extension, type /plugin in the chat to open the Manage Plugins dialog, paste AgamiAI/agami-core into the marketplace input and click Add, then switch to the Plugins tab and click Install on agami-core.

Per-host walkthroughs: docs/install/.

The trust layer

Most AI data agents quietly pick a join, quietly pick a definition of "revenue", and quietly return a number. agami makes every one of those decisions auditable:

• Confidence + review state on every entry. Each join, metric, and entity carries a flat trust block (confidence, review_state, and a sign-off identity once approved) — no vendor blobs, no scores to tune. DB-declared FKs and structural column names auto-approve; everything inferred stays unreviewed and surfaces in the Review tab.
• Metrics must be signed off (Rule 1). A metric needs an approver email, a role, and a non-empty calculation before the runtime treats it as truth — one bad metric skews every report that uses it. A query that uses an unsigned metric still answers, with a warning on the receipt. Joins & entities are lazy (Rule 2): usable while unreviewed, flagged on the receipt until confirmed.
• Every answer ships a receipt — the literal SQL, tables + row counts, relationships used (with confidence/state), metric definitions with author + date, data freshness, and the model snapshot hash. A warning banner appears if any unreviewed entry was used, and a total behind a join the model can't vouch for is reported as undetermined rather than clean. Nothing is silently trusted.
• Read-only, enforced where the SQL runs — not in the prompt. Every statement passes one executor that always refuses writes and side-effecting functions on every dialect (SLEEP, pg_read_file, Snowflake SYSTEM$…, OPENROWSET, UTL_HTTP, load_extension, …). A second pass confines it to the tables and columns the model declares (schema-qualified, so staging.orders isn't sales.orders) and refuses a projected SELECT *. That pass always runs locally; on a server it runs when AGAMI_GOVERNANCE_ENFORCED is on, which is off by default, and every answer says when it didn't run. Details: SECURITY.md.
• Snapshot-pinned. The model is YAML under ~/agami-artifacts/<profile>/ (or wherever you point AGAMI_ARTIFACTS_DIR). Make that profile folder a git repository and each curation step tries to commit there (it carries on if git can't commit, e.g. no identity set); a change that fails validation is never written. Every answer records the model snapshot hash, so old answers reproduce exactly and schema drift flips affected entries to stale instead of silently changing the number.

Full mechanics — the trust block, Rule 1/Rule 2, the review queue, the receipt, examples validation: docs/trust-layer.md.

Skills (slash commands)

Natural-language phrasing routes to each skill automatically — "open the review dashboard" / "save this as a correction" / "introspect my schema" all work without typing the slash command.

Command	What it does
/agami-connect	One-stop setup + introspect: detect/collect credentials, introspect the live DB into the semantic model (tables, columns, PK grain, FK relationships, sensitive-column flags), layer LLM enrichment, generate EXPLAIN-validated seed examples. Builds from a model spec workbook when you attach one, and asks for the one-line datasource description an agent uses to pick the right database. Validator-gated, snapshotted. Also /agami-connect sample for the no-DB sample.
/agami-query	Answers a natural-language question: picks examples + relationships, generates and runs SQL, formats the result + chart, and surfaces a provenance receipt. Flags any unreviewed entry it relied on. (Usually you don't type this — plain language routes here.)
/agami-model	One dashboard to browse, curate, and sign off the model: every table/field/metric/entity/join, per-table/column Exclude/Include, edits, new metrics. The Review tab is the trust-layer sign-off queue. Open it on the queue with /agami-model review.
/agami-save-correction	Records a correction and routes it to the right home (SQL example, column metadata, display preference, business concept, or a new metric), showing its classification before writing. Attribution surfaces on future answers it influences.
/agami-reconcile	Point it at numbers you already trust — a dashboard screenshot (Metabase / Power BI / Tableau / Looker), a CSV, or a pasted table — and it asks each question through agami and shows a side-by-side diff with tolerances. Hand it SQL you trust and it grades that query part by part against the model instead of taking it as the answer. Matching rows can be kept as golden questions.
/agami-eval	Run a golden dataset through the agent loop — every question regenerated, executed and scored against its confirmed answer key — and see, failures first, what stopped matching. It's your model's regression suite: it says whether the questions your team already agreed still get the agreed answer.
/agami-save-golden	Fill the golden dataset /agami-eval runs. Import a question bank — a CSV, one sheet of an Excel workbook, or a pasted table (rows with a statement import as confirmed, bare questions as unconfirmed) — or save one answer you just accepted, with the statement that produced it (the result you reviewed is recorded as accepted, not stored). A browsable explorer page queues changes that may weaken a claim but never grant one. Append-only: a write that would change an existing item stops for a yes.

Why not just use Claude or a bare MCP server?

You can query a database from Claude Code or a bare MCP server today — one prompt, one shot. That works for exploration. It breaks for anything you need to trust.

	Raw agent / bare MCP	agami-core
"Revenue" definition	Re-derived every query	Signed off by name + role, pinned
Join correctness	Guessed from schema hints	FK-derived or human-approved, pre-flighted
Fan trap / double-count	Silent wrong answer	Caught before SQL runs
Audit trail	None	Full receipt: SQL, model snapshot, approver
Schema drift	Silent number change	Stale flag on affected entries
Sensitive columns	Prompt-dependent	Flagged in model, enforced at runtime
Context persistence	Re-explained every session	Built once, improves with corrections

If you're exploring a database you already understand, a bare MCP is fine. If you need repeatable, governed answers you can stake a decision on, that's what this is for.

Privacy

agami runs entirely locally — credentials (chmod 600), the semantic model, charts, exports, and dashboards all live under ~/agami-artifacts/ (or the folder you chose), and the skill never reads files outside those paths (except your DB tool's auth config, set up on first connect with your permission). Details: docs/privacy.md.

Fair-code vs hosted

agami is fair-code (source-available). Everything here — introspection, the portable semantic model, NL→SQL + local execution, the trust layer, corrections, and self-hosting for your own organization — is free (serving people outside your organization needs a commercial license). The hosted cloud adds the org-scale layer on top: advanced governance and access controls (RBAC, audit, enterprise SSO with SAML/SCIM), a shared multi-tenant model registry, and scheduled evals with alerting (on-demand golden runs are in core). What's free vs paid, in full: docs/open-vs-hosted.md.

Self-hosted team server — Early access (in testing)

🧪 Early access. This team layer is usable today, but it's newer than the local single-player path and we're still ironing it out with early users — expect the occasional rough edge. Please send feedback or report anything broken via a GitHub issue. The local experience above is the stable, generally-available path.

The local setup is single-player. To put your whole team — and non-technical business users — on one governed model, deploy agami's HTTP MCP server to your own host. Everyone then connects their own Claude (claude.ai as a custom connector, or the desktop app) to one HTTPS URL and asks questions in plain language. They install nothing, touch no credentials, and only ever see the model you've governed. An admin console (/admin) controls who's allowed in; the warehouse stays behind a read-only user, and no data leaves your environment.

The paved path is one command in Claude:

/agami-deploy      # writes a ready-to-run Docker bundle: published image + HTTPS (Caddy) + OAuth + admin

It gathers your hostname and admin identity, writes docker-compose.yml + a filled agami.env (referencing the published ghcr.io/agamiai/agami-core image — no clone, no build), and either runs docker compose up locally or prints the exact VM steps and the shareable /mcp URL.

The full step-by-step — VM, DNS/TLS, and every variant (Cloudflare Tunnel, managed Postgres, Cloud Run) — is in deploy/README.md. (Prefer to wire it up by hand instead of using the bundle? The manual install + environment-variable reference covers that.) Admins sign in with a password; teammates get per-user access to /mcp.

The served tools are built to be called by an agent you don't control. All four are advertised read-only (readOnlyHint), so a client that honours the hint can skip confirming each call. The schema reply carries a model_version, and execute_sql refuses a statement written against an older one (stale_model), so a resumed conversation can't query a model that changed under it. When a datasource has curated examples, execute_sql also takes the closest example's id and whether the statement followed it or it was only shown_only — the honest answer when none fits. Calls and refusals are recorded in the activity log the admin console shows, grouped into conversations; if the log can't be reached the query is refused, and if a write fails the result is withheld.

It's cloud-neutral (a VM + Postgres, or a serverless platform + managed Postgres), configured entirely by environment variables, and LLM-free + zero-egress by default. Self-hosting this for people inside your organization is free; exposing data to people outside it is the paid line (fair-code vs hosted).

Documentation

• Quickstart & usage — first-run walkthrough + common workflows
• Credentials — every dialect, the connection-method picker
• The trust layer — confidence, sign-off, receipts, snapshots
• Format spec — the semantic-model layout + a worked example
• Model spec workbook (early) — build the model from a filled-in spreadsheet (template)
• Golden datasets — the question bank /agami-eval scores against
• Security — the read-only guarantee per dialect, and what a refusal may name
• MCP server — use agami from Claude Desktop
• Deploy a shared team server (early access — in testing) — the Docker bundle, step-by-step (VM, DNS/TLS, variants)
• Self-hosting reference — manual (non-Docker) install + the environment-variable reference
• Troubleshooting & uninstall

Contributing

Issues + PRs welcome at github.com/AgamiAI/agami-core. See CONTRIBUTING.md for test commands and the version-bump discipline — every user-visible change needs a version bump in .claude-plugin/marketplace.json (twice) and plugins/agami/.claude-plugin/plugin.json, or existing installs stay on the cached old version. Notable changes: CHANGELOG.md.

Before pushing, run the checks locally with uv run dev.py check (ruff + the test suite + gitleaks — the same gate CI runs on every PR). One-time setup and the full command list are in CONTRIBUTING.md; the coding + customer-safety conventions are in CLAUDE.md. CI gates every PR regardless.

If agami is useful to you, a ⭐ on the repo genuinely helps others find it.

License

fair-code (source-available) — the Agami Functional Use License. See LICENSE and NOTICE.

What's free vs. paid (internal use vs. external exposure): LICENSING.md.

Built by Agami AI.