An AI-powered Go CLI that analyzes SQL. Provides Socratic guidance for query optimization—craftsmanship-driven and lightweight.
KaizenSQL (kzql) was built as an exploration project focused on crafting a simple idea and enjoying the process of building.
The goal wasn't to build disruptive SQL tooling, lol. I was finishing my work hours when an idea for a CLI tool - one that reads a file and uses an AI LLM agent to diagnose it - invaded my head haha.
This project served as a playground to explore and use:
- TUI Animation: Building clean startup visuals using the Charm (
bubbletea) ecosystem. - Unix-Native CLI: Managing explicit errors, API configuration persistence, and clean execution paths in Go.
To read the full journey behind the engineering friction and lessons learned:
👉 Read the technical story on Dev.to
- Socratic Mentor Mode: Focused System Prompts designed to guide you through SQL bottlenecks without acting as a black-box query writer.
- Animated ASCII Banner: Smooth startup splash screen built with
bubbletea. - Zero-Dependency Core: Simple, standalone Go binary for Linux.
- Unix-Native: Reads files directly, outputs errors to
os.Stderr, saves config to standard directories, and respects shell exit codes.
On your first execution, kzql will ask for your Groq API key and save it in your user configuration directory (on Unix/Linux systems, that's typically ~/.config/). It will display the exact path after saving.
Groq is an LLM provider similar to Gemini or OpenAI. It's used in this project for its generous free-tier token limits. I encourage you to try it in your own projects as well, bud. 😉
| Mode | Flag | Key Analysis Points | Primary Output |
|---|---|---|---|
| Mentor (Default) | -m |
B-Tree index traversal, data page reads, and physical execution paths | No code rewrites. Provides Socratic questions & conceptual hints. |
| Performance | -p |
Non-SARGable predicates, leading wildcards, SELECT * waste, and implicit type conversions |
High-level cost diagnostic + fully optimized query rewrite. |
| Security | -s |
SQL injection risks, unconstrained UPDATE/DELETE statements, and missing atomic blocks |
Threat level rating + parameterized, hardened SQL block. |
Check the Releases section for Linux binaries and installation steps.
This project currently targets Linux (I'm not wealthy enough to afford a Mac, haha). However, you're more than welcome to clone the repository and compile it for your own OS, that's the perk of being a dev!
Special thanks to the people on the open-source world, it was a fun dev experience to work with their great software.
- Go-OpenAI by sashabaranov - Used for communicating with Groq API
- Bubbletea by charmbracelet - Text User Interface framework used to add a nice banner.
- Ascii Motion by CameronFoxly - Awesome ascii-art animation software