https://github.com/omeryasirkucuk/amx
AI-driven CLI for documenting database schemas. DB + docs + codebase agents, 10 backends, BYO LLM, human-in-the-loop review.
https://github.com/omeryasirkucuk/amx
agentic-ai ai-agents bigquery cli data-catalog data-engineering database-documentation databricks human-in-the-loop llm metadata postgre python snowflake
Last synced: 3 days ago
JSON representation
AI-driven CLI for documenting database schemas. DB + docs + codebase agents, 10 backends, BYO LLM, human-in-the-loop review.
- Host: GitHub
- URL: https://github.com/omeryasirkucuk/amx
- Owner: omeryasirkucuk
- License: apache-2.0
- Created: 2026-04-19T19:07:21.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-07T16:28:51.000Z (4 days ago)
- Last Synced: 2026-06-07T17:15:37.236Z (4 days ago)
- Topics: agentic-ai, ai-agents, bigquery, cli, data-catalog, data-engineering, database-documentation, databricks, human-in-the-loop, llm, metadata, postgre, python, snowflake
- Language: Python
- Homepage: https://amxcli.com
- Size: 64.1 MB
- Stars: 16
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
Cryptic columns, reviewed comments.
AMX walks your database, reads your codebase and docs, then drafts a
COMMENT for every table, view, and column — with confidence
scores and a human review before anything lands in the live database.
Documentation
·
Quickstart
·
Changelog
·
Issues
---
_AMX is in early development — expect breaking changes between releases. Stay current with `pip install --upgrade amx-cli`._
Three independent sub-agents — **Profile** (schema, stats, sample values), **RAG** (ingested docs), and **Code** (references mined from your repos) — gather evidence in parallel. An orchestrator merges and ranks them, you accept / edit / skip each suggestion, and AMX writes the approved text back as native `COMMENT` statements on the engine.
Five minutes from `pip install` to your first reviewed comment. **Ten database engines, seven LLM providers.**
## Install
```bash
pip install amx-cli
```
The PyPI distribution is `amx-cli`; the import package is `amx` (`import amx`). Requires Python 3.10+. See the [installation guide](https://amxcli.com/getting-started/installation/) for prerequisites, source builds, and where AMX writes config / history / logs.
## Quick start
```bash
amx # open the interactive session (the AMX REPL)
/setup # one-time wizard: DB profile + LLM profile
/connect # sanity-check the active connection
/run sales.orders # generate suggestions, review, accept
/apply # write approved descriptions back to the database
```
`/run` without an argument opens a scope picker (Database / Schema / Asset). `/run-apply` short-circuits review-and-apply when you already trust the model. If anything misbehaves, `amx doctor` runs from any shell — even when AMX itself can't start — and prints actionable hints next to each ✗.
The full guided walkthrough is at the [5-minute quickstart](https://amxcli.com/getting-started/quickstart/) and [first-run walkthrough](https://amxcli.com/getting-started/first-run/).
## AMX CLI
A typical session — running `/run`, inspecting ranked suggestions inline, accepting or editing each one before it lands in the database.
## AMX Studio (`/studio`) — same workflow on a local web UI
From inside the REPL, `/studio` boots **AMX Studio**, a token-protected web UI on `127.0.0.1`, and opens your browser. Same review-and-apply workflow as the REPL — runs, results, the pending queue, the `/ask` chat, and full DB / LLM / Docs / Code profile management — but on a denser surface. **Browse** any database / schema / table to inline-edit comments or hit per-asset **Generate** to draft just one comment through the same human-in-the-loop queue. The SPA bundle ships inside `amx-cli`; no Node toolchain or extra install needed.
Full walkthrough at [`/studio`](https://amxcli.com/cli/studio/).
## How it works
Each agent runs independently, surfaces its own evidence, and assigns its own confidence. The orchestrator picks the narrower, defensible description and ranks up to N alternatives. You never apply anything you didn't approve.
### A column, before and after
A typical column in `orders`, the kind every analytics codebase has:
```
orders.shipped_dt DATE NULL -- (no comment)
```
What AMX produces, after you approve:
```
COMMENT ON COLUMN orders.shipped_dt IS
'Date the carrier scanned the package at origin. Distinct from
order_dt (when the customer placed the order) and delivered_dt
(when the carrier recorded proof of delivery).';
confidence: high · logprob: 0.91
sources: code (3 refs) · docs · db profile
```
Every approval is recorded in local run history — re-evaluate later with `/history review` to see how the same column scores under a different model, prompt detail, or evidence mix.
## Supported database backends
PostgreSQL · Snowflake · Databricks (Unity Catalog) · BigQuery · MySQL / MariaDB · Oracle · SQL Server · Redshift · ClickHouse · DuckDB
Per-backend setup, connection details, and the capability matrix live in the [Backends section](https://amxcli.com/backends/).
## Supported LLM providers
OpenAI · Anthropic · Google Gemini · DeepSeek · OpenRouter · Ollama · vLLM / LM Studio · any OpenAI-compatible endpoint
Provider-specific guides (including OpenAI / Anthropic Batch mode and local-model setups) live in the [LLM providers section](https://amxcli.com/llm-providers/).
## Next up
- **dbt integration** — Connect dbt projects so the AMX code agent extracts table and column metadata from the transformation layer.
- **MCP integration for docs and repo** — Expose the AMX repo and docs over the Model Context Protocol so LLM clients can query them as live context.
- **CDC integration** — Detect schema changes in upstream sources and keep AMX metadata in sync.
See the [full roadmap](https://amxcli.com/roadmap/) for details.
## Documentation
Full user, operator, and contributor docs live at **[amxcli.com](https://amxcli.com/)** — concepts, the slash-command map, configuration, data sources, collaboration, troubleshooting, and the [Python API](https://amxcli.com/api/reference/) for headless use. Release notes are in [`CHANGELOG.md`](https://github.com/omeryasirkucuk/amx/blob/main/CHANGELOG.md) and on the [GitHub Releases page](https://github.com/omeryasirkucuk/amx/releases).
Recent: Studio Lineage & Variations, Confidence Scoring, and explicit cache controls — see the [changelog](https://amxcli.com/changelog/).
Recent: Studio Lineage & Variations, Confidence Scoring, and explicit cache controls — see the [changelog](https://omeryasirkucuk.github.io/amx-docs/changelog/).
## Contributing & support
- [Contributing guide](https://github.com/omeryasirkucuk/amx/blob/main/CONTRIBUTING.md) — development setup, branching, commit format, release process
- [Security policy](https://github.com/omeryasirkucuk/amx/blob/main/SECURITY.md) — how to report a vulnerability
- [Open an issue](https://github.com/omeryasirkucuk/amx/issues) — bugs, questions, feature requests
## License
Apache-2.0 — see [`LICENSE`](https://github.com/omeryasirkucuk/amx/blob/main/LICENSE).
---
_This project is developed with the help of multiple AI coding agents._