LiteBi
AgamiAI/LiteBi
Lightweight BI skill, built for Claude. Designed to run locally with no infra dependency.
Instalação
npx convez-ai AgamiAI/LiteBi1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
agami
The trust layer between AI agents and your data warehouse. Local. Private. Yours.
Ask plain-English questions of your Postgres / MySQL / Snowflake / BigQuery / Redshift / SQLite database, with a trust layer wrapped around every answer. Your credentials, schema, and query results never leave your machine — agami runs entirely inside Claude Code via the built-in Bash / Read / Write tools.
- No Agami backend. Nothing you do touches a server we operate. The plugin runs inside Claude Code; an optional local MCP server (
agami serve) lets other AI clients (e.g. Claude Desktop) use the same local model and execution — still entirely on your machine. Nopip installif you have a native CLI for your DB. See docs/mcp-server.md. - Every join is FK-derived or human-approved. Every metric is signed off with a name, role, and timestamp. The dashboard tells you which, with the source signal.
- Every answer ships a receipt — the literal SQL that ran, the model version it pinned, the relationships used, and the freshness of the source tables.
- Corrections persist with attribution. Save a fix once → every subsequent query loads it as a few-shot example, with the original author and date surfaced when it influences a future answer.
Contents
- Why agami
- The trust layer
- Quickstart (under 5 minutes)
- Install — Claude Code CLI · VS Code · Cursor
- Setup credentials
- Skills (slash commands)
- First-run walkthrough
- Common workflows
- Privacy
- Troubleshooting
- Format reference
- Contributing
- License
Why agami
Most NL→SQL tools either send your data through a hosted backend (Snowflake-flavored ChatBI, Hex, etc.) or require a heavy local install (a database proxy, a fine-tuned model, a Python package). agami does neither — and goes further: it gives a data engineer the mechanical primitives to verify why an answer is correct, not just whether it ran.
- Local execution. The skill reads your
<artifacts_dir>/local/credentialsfile, runs SQL through your existingpsql/mysql/snowsql/bq/sqlite3/ DuckDB binary, parses the rows, and shows you the answer. No data path through any server we operate. - Zero infra. Just a Claude Code skill plugin and a tree of YAML files under
~/agami-artifacts/<profile>/. If you have a DB CLI, you have everything you need. - Diffable, git-native. The semantic model is YAML under
~/agami-artifacts/<profile>/(org.yaml+subject_areas/<area>/…).agami-connectrunsgit initon that tree and commits each introspect — every model change is a diff you can review, blame, and revert. - Snapshot-pinned answers. Every query records the model snapshot hash it ran against. Old answers reproduce exactly. Schema drift flips affected entries to
staleinstead of silently changing the number. - Corrections persist with attribution. When you say "no, the join should be on
customer_id", the corrected SQL lands inexamples.yamlwith the author and date. When a future answer is influenced by it, the receipt names the correction's author so the audit trail stays clean.
agami is open source under the Apache 2.0 license (with an explicit patent grant). The code that runs on your machine is the code in this repo. Read it.
The trust layer
Most "AI BI" tools quietly pick a join, quietly pick a definition of "revenue", and quietly return a number. agami makes every one of those decisions auditable — with one knob per workspace and one queue per curator.
Every entry carries a confidence + a review state
agami-connect writes each join, metric, and entity with a flat trust block — a confidence label, a review state, and (once approved) a sign-off identity. No vendor blobs, no numeric scores to tune:
# a relationship in subject_areas/<area>/relationships.yaml
- from_table: orders
to_table: customers
from_column: customer_id
to_column: id
relationship: many_to_one
confidence: confirmed # confirmed | inferred | proposed
review_state: approved # unreviewed | approved | rejected | stale | not_applicable
signed_off_by: null # set when a human approves
signed_off_at: null
signed_off_role: null # cfo | cto | data_lead | engineer | analyst | other
A metric carries the same block plus its definition — prose calculation + per-dialect bindings — so an answer can show exactly what "revenue" means and who vouched for it.
Auto-approve collapses the queue to what actually needs human eyes:
- A DB-declared foreign key → relationship
confidence: confirmed,review_state: approved(the database already vouches for it). - A probe-inferred join (name + value overlap, no declared FK) →
confidence: proposed/inferred,review_state: unreviewed. - A column with a self-evident structural name (
id,*_id,created_at,email,status,is_*/has_*flags…) needs no description and is never queued. Full list atplugins/agami/shared/column-name-dictionary.md.
Everything inferred stays unreviewed and surfaces in the Review tab.
Rule 1 vs Rule 2 — and the hybrid review order
- Rule 1 — metrics (always queue): a metric must be signed off — a
signed_off_byemail AND asigned_off_roleAND a non-emptycalculation— before the runtime treats it as truth. Highest blast radius: one bad metric skews every report that uses it. The validator enforces all three before a metric can beapproved. - Rule 2 — joins & entities (lazy): usable while
unreviewed; they self-approve as you query and surface as receipt warnings until confirmed. No threshold to tune — it's review state, not a number.
At runtime, agami-query still answers questions that use unreviewed metrics, joins, or entities — but every unreviewed entry it relied on surfaces as a warning in the receipt (e.g. "Used metric revenue which has not been signed off"), with a one-click link to the Review tab. Nothing is silently trusted; nothing is hard-blocked. Only rejected (excluded) entries are dropped entirely — those never appear in an answer.
Hybrid review order in /agami-connect: Phase 4 surfaces a Rule 1 sign-off gate before seed examples are generated (Phase 5). Reason: seed SQL exercises metric definitions; signing them off first means the seeds inherit approved truth instead of LLM guesses. Rule 2 polish (low-confidence joins / field descriptions) stays in Phase 7's optional collapsed panel — it self-approves as the user queries and never blocks the path to first answer.
The review queue (a tab of the model dashboard)
/agami-model review (or "open the review dashboard") opens the model dashboard on its Review tab — the trust-layer sign-off queue. (This was a standalone /agami-review command; it's now one tab of the single model dashboard, so browsing the model and signing it off happen in one place.) The queue splits into Needs your eyes (Rule 1 metrics, low-confidence or drifted entries) and Looks right (confident) (FK-derived joins, clearly-defined entries) with a one-click "Approve all". Each card shows:
- The inferred SQL fragment / definition / mapping
- Its confidence + review state
- An inline editable textarea for the description /
calculation - Per-card Approve / Reject / Edit buttons + group-level "Approve all"
Approving stamps the curator's email + role (resolved once and saved). Click through the queue, hit "Generate feedback for Claude" at the bottom, paste back into chat. agami applies each edit, runs the validator, commits the result to <artifacts_dir>/<profile>/.git/, and re-renders.
Every answer ships a receipt
Every agami-query answer includes a "Provenance for this answer" panel:
- The literal SQL that ran (no paraphrase)
- Tables touched + row count per table
- Relationships used, each with its confidence + review state
- Metric definitions invoked, with author + sign-off date
- Named-filter predicates used (named, not anonymous)
- Source-data freshness per table (when the DB exposes it)
- Model snapshot hash (so the answer is reproducible from
<artifacts_dir>/<profile>/.snapshots/<hash>/) - A warning banner if any unreviewed entry was used
Examples validation
Phase 5 of agami-connect generates 10–12 NL→SQL seed examples that each satisfy one of five analytical shapes: aggregation with a measure, segmentation, time comparison, filtered top-N with context, or cohort / retention. Plain row-listing is disqualified. Each seed is EXPLAIN-validated against the live DB, then surfaced in an examples-validation dashboard (<artifacts_dir>/local/examples-validation/<ts>.html) — same per-card pattern as the review dashboard, with Validate / Reject / Edit / Add note buttons + an inline "Add example" affordance.
Quickstart (under 5 minutes)
# 1. Install the plugin — see the Install section below for the exact steps
# per host. CLI uses /plugin marketplace add; VS Code and Cursor use the
# "Manage Plugins" dialog.
# 2. Run connect — picks your DB type, writes <artifacts_dir>/local/credentials.example
# (first time only; subsequent runs introspect directly)
/agami-connect
# 3. Edit the template with your DB connection details
$EDITOR <artifacts_dir>/local/credentials.example
mv <artifacts_dir>/local/credentials.example <artifacts_dir>/local/credentials
chmod 600 <artifacts_dir>/local/credentials
# 4. Re-run connect to introspect: build the semantic model + seed examples
/agami-connect
# (mid-flow: signs off any metrics in a Rule 1 sign-off gate, then generates
# seed examples and opens the examples-validation dashboard)
# 5. (Optional) walk the Rule 2 polish queue when you have time
/agami-model review
# 6. Ask a question
how many orders did we ship last month?
/agami-connect is one-stop: it picks up missing credentials on first run, introspects the live DB, computes confidence on every entity, auto-approves the high-signal ones (FK joins, DBA-commented fields, structural column-name patterns), gates a Rule 1 sign-off before generating seeds (so the seeds inherit approved metric definitions), renders the examples-validation dashboard, and leaves the Rule 2 long tail in an optional collapsed panel that self-approves as you query. By step 6 you're answering questions with the receipt panel showing exactly which entries each answer touched.
Install
Platform note. The skills are validated on macOS and Linux. They run shell commands in
bash, so on Windows they require Git for Windows (Claude Code uses Git Bash for its Bash tool when present; without it the Bash tool falls back to PowerShell, where these commands don't run). Windows is not yet validated end-to-end. (The optional local MCP server for Claude Desktop is pure-stdlib Python and is cross-platform — see docs/mcp-server.md.)
The same plugin works across all four hosts. Pick yours:
Claude Code CLI
# In any terminal:
claude
In the Claude Code prompt:
/plugin marketplace add AgamiAI/LiteBi
/plugin install agami@litebi
Verify:
/plugin list
You should see agami@litebi v0.2.2.
Detailed walkthrough: docs/install/claude-code-cli.md.
Claude Code in VS Code
- Install the Claude Code extension from the VS Code marketplace (publisher: Anthropic).
- Open the Claude pane (Cmd+Shift+P → "Claude Code: Open").
- In the chat input, type
/plugin. This opens a Manage Plugins option — click it. - The plugins dialog opens. Add the marketplace:
- Paste
AgamiAI/LiteBiin the marketplace input - Click Add
- Paste
- Switch to the Plugins tab in the dialog.
- Find
agamiin the list and click Install.
Detailed walkthrough: docs/install/claude-code-vscode.md.
Claude Code in Cursor
- Install the Claude Code extension from the Cursor extensions marketplace (or via
cursor --install-extension anthropic.claude-code). - Open the Claude pane.
- In the chat input, type
/plugin. This opens a Manage Plugins option — click it. - The plugins dialog opens. Add the marketplace:
- Paste
AgamiAI/LiteBiin the marketplace input - Click Add
- Paste
- Switch to the Plugins tab in the dialog.
- Find
agamiin the list and click Install.
Detailed walkthrough: docs/install/claude-code-cursor.md.
Setup credentials
agami reads database connection details from <artifacts_dir>/local/credentials. Same pattern as ~/.aws/credentials, ~/.dbt/profiles.yml, ~/.pgpass.
/agami-connect creates a template at <artifacts_dir>/local/credentials.example on first run (its Phase 0a — formerly the separate /agami-init skill). Edit it and save as <artifacts_dir>/local/credentials:
[default]
type = postgres
host = localhost
port = 5432
database = mydb
user = myuser
password = mypassword
Then make it readable only by you:
chmod 600 <artifacts_dir>/local/credentials
agami refuses to read the file unless it's chmod 600 — the same protection ssh uses for private keys.
Multiple databases
Add more [<profile>] sections. Switch with AGAMI_PROFILE=staging:
[default]
type = postgres
host = prod-db.example.com
...
[staging]
type = postgres
host = staging-db.example.com
...
MySQL example
[default]
type = mysql
host = 127.0.0.1
port = 3306
database = analytics
user = analyst
password = secret
Snowflake example
[finance]
type = snowflake
account = xy12345.us-east-1.aws
user = analyst@example.com
password = secret
warehouse = COMPUTE_WH
role = ANALYST_ROLE
database = ANALYTICS
schema = PUBLIC
# Or use SSO:
# authenticator = externalbrowser
BigQuery example
[gcp]
type = bigquery
project = my-gcp-project
dataset = analytics # optional default dataset
service_account = /abs/path/to/key.json # omit to use Application Default Credentials
location = US # optional, defaults to US
Redshift example
[warehouse]
type = redshift
host = my-cluster.abc123.us-west-2.redshift.amazonaws.com
port = 5439
database = analytics
user = readonly
password = secret
sslmode = require # default; verify-full / verify-ca / disable all accepted
SQLite example
[local]
type = sqlite
path = /Users/me/data/local.db
Full format reference
plugins/agami/shared/credentials-format.md — every field, every database, every edge case.
No Python required (usually)
The skill picks the first available connection method, in this order:
| Method | What you need | Install if missing |
|---|---|---|
| Native CLI | psql (Postgres / Redshift) / mysql (MySQL) / snowsql (Snowflake) / bq (BigQuery) / sqlite3 (SQLite) on PATH | brew install postgresql / brew install mysql / snowsql download / gcloud SDK |
| DuckDB universal binary | duckdb on PATH (covers Postgres / MySQL / SQLite, not Snowflake / BigQuery) | brew install duckdb (or duckdb.org) |
| Python driver (fallback) | Python + psycopg2-binary / pymysql / snowflake-connector-python / google-cloud-bigquery | pip install psycopg2-binary pymysql snowflake-connector-python google-cloud-bigquery |
/agami-connect Phase 0a tells you exactly what to install for your OS if nothing is detected.
Skills (slash commands)
| Command | What it does |
|---|---|
/agami-connect | One-stop setup + introspect. First run: detects missing credentials, runs the DB-type picker (Postgres / Supabase / Redshift / MySQL / Snowflake / BigQuery / SQL Server / Oracle / Databricks / Trino / DuckDB / SQLite), writes <artifacts_dir>/local/credentials.example for you to fill in, verifies the connection method, and ends the turn. Re-invoke after filling in the file → introspects the live DB directly into the semantic model at ~/agami-artifacts/<profile>/ (subject areas, tables, columns, primary-key grain, foreign-key relationships with join cardinality, deep-table column groups, sensitive-column flags) — in catalog mode, or a probe-mode fallback when the catalog is locked down — then layers LLM enrichment (descriptions, entities, metrics), generates EXPLAIN-validated seed examples, and opens the examples-validation dashboard. Validator-gated; runs git init and snapshots under .snapshots/<hash>/. |
/agami-query | Answers a NL question. Picks examples + relationships, generates SQL, runs it, formats the result, and surfaces a SQL receipt panel (provenance + model-version pin). If it uses an unreviewed metric / join / entity, it still answers but flags each as a warning on the receipt. (You usually don't need to type this — natural language routes here.) |
/agami-model | One dashboard to browse, curate, AND sign off the model. A static HTML browser with tabs (Organization · Review · Tables · Metrics · Entities · Joins · Examples · Queued), live search, and per-tab status filters. Browse/curate: every table / field / metric / entity / join with descriptions; per-table + per-column Exclude / Include; edit any description / metric / entity / join; add new metrics; edit ORGANIZATION.md. Review (the former /agami-review): the Review tab is the trust-layer sign-off queue — Approve / Reject metrics (Rule 1 — answers that use an unsigned one carry a warning until you approve it), entities, and inferred joins (Rule 2, lazy), with a one-click "Approve all" for the confident ones. Excluded/rejected entries drop out of the runtime model (joins, prompts, aggregates) but stay in the YAML for audit. Open it on the queue with /agami-model review. All actions queue into one "Generate feedback for Claude" block; the engine validates + commits each batch. |
/agami-save-correction | Records a correction and routes it to the right destination via a 5-way classifier: SQL pattern → examples.yaml; per-column meaning / value normalization → the column's description / choice_field in the semantic model; cross-DB display preference → USER_MEMORY.md; abstract business concept tied to this DB → ORGANIZATION.md; new reusable aggregation → metric in the semantic model. Surfaces the classification + destination + reasoning before writing, so you can override. The next answer that uses the correction surfaces its attribution in the receipt. |
/agami-reconcile | Reconciliation harness: point it at a legacy dashboard's CSV (label → number rows) and it generates each NL question, runs it through agami, and shows a side-by-side diff with tolerances. Use to validate the model against numbers you already trust. |
/agami-serve | Use agami from the Claude Desktop app, not just Claude Code. Wires up the optional local MCP server (scripts/mcp_server.py) in one step: auto-detects the right Python, copies the self-contained server to a stable <artifacts_dir>/local/serve/, and safely merges into claude_desktop_config.json (timestamped backup, every other key preserved). The server exposes the same tools as the hosted Agami connector, backed by your local model + local execution — stdio only, read-only SQL, no network, no auth. See docs/mcp-server.md. |
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.
First-run walkthrough
$ /agami-connect
[Phase 0: preflight — no credentials yet, running first-time setup]
> Pick your database: PostgreSQL · MySQL · Snowflake · BigQuery · Other
You: Snowflake
✓ Wrote <artifacts_dir>/local/credentials.example with a [main] section for Snowflake.
Fill it in (account, user, password OR authenticator=externalbrowser,
warehouse, role, database, schema) then save as <artifacts_dir>/local/credentials.
# After filling in the file:
$ /agami-connect
[Phase 0: preflight]
✓ <artifacts_dir>/local/credentials present (chmod 600)
✓ Tier detected: snowsql (Tier 2 — native CLI)
[Phase 1: introspect]
✓ 14 tables across 1 schema (ANALYTICS)
✓ 0 FK relationships declared (Snowflake — typical)
✓ 23 inferred relationships from column-name + unique-index match
[Phase 2c: trust spine]
✓ Confidence computed for every dataset, field, relationship
✓ 187 field descriptions auto-approved (DBA column comments / structural pattern match)
✓ 21 relationships auto-approved (unique-index + plural-pattern match)
⚠ 8 metric proposals stamped Rule 1 (need human sign-off)
⚠ 14 inferred relationships unreviewed (lazy — confirm as you query)
[Phase 3: validate + write]
✓ Validator passed (semantic-model schema + trust block)
✓ Wrote the model under ~/agami-artifacts/main/ (org.yaml + subject_areas/…)
✓ Snapshot pinned at .snapshots/45f0fefa2403/
✓ git init + initial commit
[Phase 4: Rule 1 sign-off — BEFORE seed generation]
8 metric proposals need your sign-off — seeds will exercise these
definitions, so signing them off first means the seeds inherit
approved truth instead of LLM guesses.
Opening Rule 1 review dashboard…
<artifacts_dir>/local/review/main/20260511-204100.html
You (in dashboard): click Approve on 6 metrics by you@example.com role=data_lead,
Edit 1 (calculation tweak), Reject 1.
Generate feedback → paste back.
✓ Applied: 7 approved (1 with edit), 1 rejected. Rule 1 complete.
[Phase 4: seed examples]
Generating 10–12 NL→SQL seed examples and EXPLAIN-validating each
against the live database. Expect 1–3 minutes…
[1/11] Top 5 customers by lifetime spend — EXPLAIN ✓
...
✓ Generated 11 seed examples (≥6 multi-table, ≥1 time-comparison shape)
[Phase 5: examples validation]
Rendered dashboard: <artifacts_dir>/local/examples-validation/main/20260511-204500.html
You (in chat): validate 1, 3, 4, 5, 7 by you@example.com
edit 8 sql>>>
SELECT ...
<<<
note 4 >>>
Format counts with commas
<<<
done
✓ Validation complete: 6 validated, 1 edited, 4 unreviewed (errors).
[Phase 7: trust-layer landing — Rule 1 already done]
✓ Rule 1 sign-off complete · 7 items approved earlier this session
Optional polish (low-confidence Rule 2 entries — won't block):
⚠ 14 inferred relationships unreviewed (lazy — confirm as you query)
⚠ 23 field descriptions awaiting review
Open the Rule 2 polish queue? (y / skip — they self-approve as you query)
You: skip
You: how many customers placed an order in the last 30 days?
The receipt panel on the answer shows the SQL that ran, the relationships used (with their confidence + review state), and the model version (.snapshots/45f0fefa2403/). If a query touched an unreviewed entry, the receipt has a warning banner pointing back at /agami-model (its Review tab).
Common workflows
Ask a question
top 10 active customers by spend last 30 days
The skill loads your model + examples, generates SQL, runs it, returns a markdown table AND a chart (by default — every result gets a chart unless the shape doesn't lend itself to one). The receipt panel below the chart shows the SQL, the tables touched, the relationships used (with confidence + review state), and the model snapshot hash. If a touched table is large (> 1M rows) without a date filter, the skill prompts you before running.
If the question relies on a definition with multiple candidates — e.g. you ask "show me revenue" and there are three revenue-synonym metrics — the skill asks you which one, instead of silently picking.
Open the review dashboard
You: open the review dashboard
# or: /agami-model review
# (the Review tab lists everything needing sign-off; confident items have a one-click "Approve all")
Walk the cards. Each shows the inferred SQL + signal breakdown + an inline editable textarea. Click Approve / Reject / Edit on the cards you want, then hit "Generate feedback for Claude" at the bottom and paste back. agami applies each edit, runs the validator, commits to <artifacts_dir>/<profile>/.git/, and re-renders to a new timestamped HTML file.
Browse the model + exclude tables / columns
You: open the model explorer
# or: /agami-model
# or: "remove the staging tables and PII columns from the model"
Renders a self-contained HTML browser of every subject area → table → field → metric → entity → join. Dedicated tabs surface every metric (with its prose calculation + per-dialect bindings), entity, and relationship so you can see exactly what the model contains without reading YAML.
Live search across names + types + descriptions + metric prose + filter predicates. Filter chips (All / Active / Excluded / Unreviewed / Queued for change), per-table + per-column Exclude / Include buttons. Useful when:
- You want PII columns hidden from agami without changing access at the DB level.
- A re-introspect pulled in staging / archive tables you don't want considered.
- You want to scan field names across the whole schema (e.g. "where do we have
created_atcolumns?"). - You want a single view of every metric definition the trust layer is enforcing.
Excluded entries flip agami.review_state to rejected. The runtime model loader filters them out everywhere — they never appear in prompts, never get joined to, never get aggregated. The YAML still has them, so you can re-include later. The HTML is static and rendered by Python; no LLM tokens are spent on the YAML walk.
Save a correction (with attribution)
You: top customers should rank by lifetime spend, not just last 30 days
[agami regenerates and shows the corrected query]
You: save this as a correction
[agami classifies the correction and shows you where it'll land:
→ routing to: examples.yaml example #N (SQL pattern fix)
→ reasoning: "the corrected SQL changes the ranking expression — this
is a SQL pattern correction, not a per-column rule"
Confirm or override?]
agami's save-correction classifier routes to one of five destinations based on what the correction is actually fixing:
| What the correction fixes | Where it lands |
|---|---|
| SQL pattern (join columns, aggregation expression, filter shape) | examples.yaml as a new few-shot example |
| Per-column meaning, unit, sign convention, or value normalization (Male/MALE/T → "Male") | The column's description / choice_field / caveats in its table YAML |
| Cross-DB display preference (format counts with commas, default time window) | USER_MEMORY.md (+ updates the seed example's SQL to demonstrate the formatting) |
| Abstract business concept tied to this DB ("gold tier means lifetime spend > $10k") | ORGANIZATION.md |
| Reusable aggregation that didn't exist before ("MRR = SUM(price) WHERE plan_type='subscription'") | New metric in the semantic model (sign-off required — Rule 1) |
The classifier surfaces its decision before writing, so you can override if it picks wrong. The next answer that uses the correction surfaces its attribution in the receipt: "this answer was influenced by a correction from you@example.com on 2026-05-11: 'use lifetime spend not 30-day window.'"
Render a chart
Charts are produced by default for every query result. To request a specific shape:
You: make that a bar chart by customer
The skill writes <artifacts_dir>/local/charts/<ts>.html — self-contained Chart.js, the SQL receipt embedded as a collapsible panel. Supported: bar, line, pie, doughnut, scatter. Tables paginate at 20 rows.
Export to CSV
You: export this
Writes the full result (no row cap) to <artifacts_dir>/local/exports/<ts>.csv.
Reconcile against a legacy dashboard
When you've inherited a number from Tableau / Looker / a spreadsheet and want to verify the model returns the same:
You: /agami-reconcile ~/Downloads/q3-revenue-by-region.csv
Parses the CSV (auto-detects headers + number formatting — currency, magnitude suffixes, accounting parens, percentages), generates the matching NL question for each row, runs it through agami, and shows a side-by-side diff. Matches are green; mismatches drill into the receipt so you can see why the two numbers disagree (typically a definitional disagreement, which is exactly what the trust layer is for).
Edit the semantic model by hand
Open the table YAML at ~/agami-artifacts/<profile>/subject_areas/<area>/tables/<table>.yaml (or the area's metrics/, entities/, relationships.yaml). Add a description, refine a metric's calculation/bindings, add caveats. Save. The next query picks it up — no skill restart needed.
If you flip a review_state from unreviewed to approved by hand on a relationship or metric, also set signed_off_by, signed_off_at, and signed_off_role — the validator will reject the file otherwise.
Format reference: docs/format-spec.md and the Pydantic models at plugins/agami/scripts/semantic_model/models.py.
When the database schema changes (new tables / new columns / dropped columns)
Re-run /agami-connect reintrospect (or just /agami-connect and pick "Refresh the schema"). agami doesn't watch your DB for drift automatically — you have to kick the refresh yourself.
What survives the re-introspect (your hand-edits are not lost):
- Descriptions,
choice_fieldmaps, metric definitions, entities - Trust-layer sign-offs (
signed_off_by/signed_off_at/signed_off_role) on every unchanged entry - The rule is: the DB is canonical for structure (tables / columns / types / PK / FK); the YAML is canonical for meaning (prose, business definitions, approvals)
What happens to the new stuff:
| Change | Behavior |
|---|---|
| New tables | Fresh trust blocks per Phase 2c.2. FK relationships auto-approve where the DB declares them; structural column-name patterns (id, *_id, created_at, email, ...) auto-approve via the dictionary. Anything else stays unreviewed. |
| New columns on existing tables | Same — pattern-matched columns auto-approve, others land unreviewed. |
| New metric | If Phase 4 detects any new Rule 1 candidates, the Rule 1 gate fires before Phase 5 regenerates seed examples. Sign them off, then seeds inherit approved definitions. |
What happens to drift (column type change, FK target shift):
- The entry's
agami.review_stateflips tostale. Priorsigned_off_*is preserved for audit. - At runtime,
agami-querystill answers but warns when a query touches astaleentry (schema drift) — surfaces as: "This used X, marked stale (schema drift). Run /agami-connect to re-introspect, then /agami-model to reconcile."
What happens to removed tables / columns (the lossy case):
- They drop out of the model on the next write. Hand-edits on them (descriptions, sign-offs) are lost.
.git/in<artifacts_dir>/<profile>/keeps the history —git logandgit show <commit>:<path>recover prior versions if needed..snapshots/keeps prior model versions pinned, so old query receipts still resolve the entries they referenced.
Workflow:
git -C ~/agami-artifacts/<profile> log -5 # optional: see what's there
/agami-connect reintrospect
# Walk Phase 4 if a Rule 1 gate fires (new metrics need sign-off)
# Walk Phase 5 examples-validation (can skip with `done`)
# Walk Phase 7's Rule 2 polish panel if you want (or skip)
git -C ~/agami-artifacts/<profile> diff HEAD~1 # diff of what the schema change cost / added
Known gap: no automated drift detection yet. You have to know the schema changed. A "drift inbox" feature (watch DB metadata, surface changes proactively) is in the plan but unbuilt — the v1 contract is manual re-introspect.
Snapshot reproducibility
Every introspect writes the canonical model to ~/agami-artifacts/<profile>/.snapshots/<hash>/. Every query records that hash in its receipt. To reproduce an old answer exactly, git checkout the matching commit in <artifacts_dir>/<profile>/.git/ — the model that produced the original number is byte-identical.
Switch profiles (multi-database)
AGAMI_PROFILE=staging
Or in chat: "switch to the staging profile". Per-profile artifacts live under ~/agami-artifacts/<profile>/; credentials live in the same <artifacts_dir>/local/credentials file but under a different [<profile>] section.
Privacy
agami runs entirely locally.
What lives on your machine:
<artifacts_dir>/local/credentials(chmod 600) — DB connection details. Never read by anything outside the skill scripts in this repo.<artifacts_dir>/local/.config— your reviewer email + role (for trust-layer sign-offs). The artifacts-dir location is the~/.config/agami/pathpointer (orAGAMI_ARTIFACTS_DIR).~/agami-artifacts/<profile>/— the semantic model (org.yaml + subject_areas/), examples, ORGANIZATION.md, snapshots, curation log,corrections.jsonl,.git/history.<artifacts_dir>/local/charts/<profile>/<ts>.html— rendered charts (per profile).<artifacts_dir>/local/exports/<profile>/<ts>.csv— CSV exports (per profile).<artifacts_dir>/local/review/<profile>/<ts>.html,<artifacts_dir>/local/examples-validation/<profile>/<ts>.html,<artifacts_dir>/local/model/<profile>/<ts>.html— dashboards (per profile).
The skill never reads files outside those paths (except your DB tool's auth config — ~/.pg_service.conf, ~/.snowsql/config, etc. — which it sets up on first connect with your permission).
Reduce permission prompts (built in)
Claude Code prompts for permission the first time it runs a Bash command pattern. agami ships its allowlist as part of the plugin's .claude/settings.json — when you install agami via the marketplace, the host picks up these defaults automatically. No copy-paste step needed.
The shipped allowlist covers the common agami invocation shapes: psql / mysql / snowsql with auth files, the bundled scripts (execute_sql.py / setup_pgauth.py / render_chart.py / build_duckdb_attach.py / the semantic_model package), mkdir/chmod on <artifacts_dir>/local/ and ~/agami-artifacts/, open on chart files, and the GitHub-star ask URL. It does NOT auto-allow arbitrary psql / mysql invocations against your DB — only the wrapper scripts that read credentials safely.
To override per-user (e.g., to add commands you trust beyond agami), put them in ~/.claude/settings.local.json — Claude Code merges that on top of the shipped allowlist. That file is gitignored; your additions stay private.
Troubleshooting
| Symptom | Fix |
|---|---|
<artifacts_dir>/local/credentials must be chmod 600 | chmod 600 <artifacts_dir>/local/credentials |
psql: command not found | brew install postgresql (or use DuckDB: brew install duckdb) |
mysql: command not found | brew install mysql (or DuckDB) |
bq: command not found | Install the gcloud SDK and run gcloud components install bq. Or pip install google-cloud-bigquery for the Python path. |
snowsql flag-guessing failures | Snowflake CLI is fussy about flag ordering; use the explicit invocation table in connection-reference.md. |
connection refused on a remote DB | Check VPN / firewall, then connect with your native CLI (psql -h ... -U ... or snowsql -a ... -u ...) directly to confirm. |
"I don't have a model for <profile>" | Tell agami "introspect my schema" or run /agami-connect. The skill picks up AGAMI_PROFILE automatically. |
| The generated SQL keeps using a column that doesn't exist | The model is stale. Run /agami-connect reintrospect — it preserves your hand-edits, refreshes from the DB, and surfaces any new entries in the review queue. See When the database schema changes. |
| Just added new tables / columns / metrics to your DB | Run /agami-connect reintrospect. Same as above — hand-edits + sign-offs survive; new structure flows in; drifted entries flip to stale. |
| Query times out on a large table | Add a date filter or LIMIT; the skill flags HIGH-risk scans before running. |
| "agami warned that revenue isn't signed off" | The answer still came back — the warning just means the revenue metric is unreviewed. Open /agami-model (Review tab), check the metric (or fix its calculation if it's wrong), and approve it; the warning then disappears. |
| Validator rejects a hand-edited YAML | Read the error verbatim — it'll point at the exact line. Most common: a metric set to approved without signed_off_by/signed_off_role, or a non-empty calculation. |
| Want to switch profiles | AGAMI_PROFILE=staging then re-ask the question. |
If you hit a case not in the table, file an issue at github.com/AgamiAI/LiteBi/issues with the exact error, your DB type, and what the validator says (python3 -m semantic_model.cli validate ~/agami-artifacts/<profile>).
Format reference
- Semantic model — a provider-portable, standard-concepts hierarchy: Organization → Storage Connection (physical) + Subject Area (logical) → Table / Column / Entity / Metric / Relationship, with declarative fields (default_filters, value_transform, caveats, value_pattern, sensitive, join cardinality) any LLM can traverse. The Pydantic models are the spec:
plugins/agami/scripts/semantic_model/models.py; the on-disk layout + a worked example are indocs/format-spec.md. - Trust block — every relationship + metric (and, for exclusion, every table/column/entity) carries
confidence(confirmed/inferred/proposed),review_state, andsigned_off_by/at/role. The validator + curation engine live inplugins/agami/scripts/semantic_model/(validator.py,curate.py). - File layout (
plugins/agami/shared/file-layout.md) — what lives where under~/agami-artifacts/<profile>/and how the snapshot directory works. - Examples library YAML —
<artifacts_dir>/<profile>/prompt_examples/<area>/examples.yaml, the NL→SQL few-shot library. Entries carrysource: seed|correction|manual,state: unreviewed|validated|rejected,validated_by,validated_at. - Credentials INI (
plugins/agami/shared/credentials-format.md) —<artifacts_dir>/local/credentials(all 6 DB types). - Connection methods (
plugins/agami/shared/connection-reference.md) — how the skill picks between psql / mysql / snowsql / bq / sqlite3 / DuckDB / Python drivers, including per-tierSELECT 1probe invocations. - Introspect queries (
plugins/agami/shared/introspect-queries.md) — the dialect-specific INFORMATION_SCHEMA queries eachagami-connectrun uses. - SQL generation rules (
plugins/agami/shared/sql-generation-rules.md) — safety + grain-guard rules applied before execution.
Uninstalling
Removing the plugin via the Claude Code marketplace UI marks it disabled, but the on-disk cache (and your data + settings) survive in case you reinstall later. To fully clean up:
# 1. Optional: archive your tuned semantic model first (in case you come back)
tar czf ~/agami-backup-$(date +%Y%m%d).tar.gz ~/agami-artifacts # model + local/ (credentials, config) — all in one folder now
# 2. Remove the plugin's on-disk cache (Claude Code doesn't auto-purge this)
rm -rf ~/.claude/plugins/cache/litebi
rm -rf ~/.claude/plugins/cache/agami-skills # only if you also installed our pre-LiteBi marketplace
# 3. Remove your data (only if you're sure you don't want it back)
# Snapshot files are intentionally immutable — chmod first so rm can delete them.
chmod -R u+w ~/agami-artifacts 2>/dev/null
rm -rf ~/agami-artifacts # semantic model, examples, ORGANIZATION.md, USER_MEMORY.md, .snapshots/, .git/
rm -rf <artifacts_dir>/local # credentials, .config, charts, exports, review + examples-validation dashboards
# 4. Restart Claude Code (full quit, not just close window)
If the slash commands /agami-connect, /agami-query, etc. still appear after step 4, you have another LiteBi version cached at a different path. find ~/.claude -type d -name "litebi*" will show every copy.
Contributing
Issues + PRs welcome at github.com/AgamiAI/LiteBi. See CONTRIBUTING.md for the 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, otherwise existing installs stay on the cached old version forever.
Local dev iteration
For fast iteration without /plugin marketplace update round-trips:
-
Symlink the plugin cache to your repo so file edits are live:
# Back up first; the installed version directory varies by your last install mv ~/.claude/plugins/cache/litebi/agami/<installed-version> \ ~/.claude/plugins/cache/litebi/agami/<installed-version>.backup ln -s /path/to/LiteBi/plugins/agami \ ~/.claude/plugins/cache/litebi/agami/<installed-version>Run
/reload-pluginsin Claude Code to pick up new skills. -
dev/reset-yamls.sh <profile>wipes just the artifact YAMLs (~/agami-artifacts/<profile>/org.yaml, thesubject_areas/tree, snapshots) so you can re-run/agami-connectagainst your test DB without re-typing credentials or losing your reviewer email / role. Flags:--hard(also dropsORGANIZATION.md,.git/, audit logs),--clean-renders(also wipes that profile's rendered dashboards),--clean-renders-all(also wipes legacy flat-layout files),--dry-run(preview). -
python3 -m pytest tests/ -qruns the suite (287 tests, ~3 seconds). Covers the renderers, validator, confidence formulas, applier, reconcile parser — basically everything that doesn't need an LLM round-trip.
A community Discord will land soon — once it's live the link will appear here and in agami-connect/SKILL.md.
License
Apache License, Version 2.0. See LICENSE and NOTICE.
Built by Agami AI.