The Problem
Software‑engineering teams that rely on generative‑AI assistants (Claude Code, Cursor, Gemini CLI, Codex CLI) have no built‑in way to capture why a suggestion was accepted, what evidence supports it, or how competing ideas were evaluated. The result is a “black‑box” chat history that cannot be audited or reused across projects.
What This Does
quint-code implements the First‑Principles Framework (FPF) as a Go‑based command‑line tool that forces a hypothesis‑driven workflow:
q0‑init creates a project‑local .quint/ store and a .mcp.json server config. q1‑hypothesize (or q1‑add) records competing hypotheses in the store. q2‑verify, q3‑validate, q4‑audit, and q5‑decide guide the user through logical checks, evidence collection, bias audits, and final decision logging.
All state lives in plain‑text markdown files under .quint/, making the audit trail queryable and version‑controlled. The CLI is thin; the heavy lifting lives in src/mcp/internal/fpf/ (FSM, projection, preconditions) and the SQLite‑backed persistence layer in src/mcp/db/.
How To Use It
Install the binary (recommended)
curl -fsSL https://raw.githubusercontent.com/m0n0x41d/quint-code/main/install.sh | bash
Or build from source
git clone https://github.com/m0n0x41d/quint-code.git cd quint-code/src/mcp go build -o quint-code . sudo mv quint-code /usr/local/bin/
Initialise a new project (run inside the project root) quint-code init # creates .quint/ and .mcp.json
Example reasoning session
/q0-init /q1-hypothesize "Replace legacy auth with OIDC" AI writes hypotheses to .quint/hypotheses.md /q2-verify # runs logical checks defined in internal/fpf/preconditions.go /q3-validate # executes test scripts or external queries /q4-audit # generates bias report (src/mcp/internal/fpf/tools.go) /q5-decide # records final decision in .quint/decision.md
Configuration files are simple JSON/YAML placed alongside the binary:
.mcp.json – MCP server settings (see src/mcp/cmd/init.go). .quint/ – stores hypotheses.md, evidence/, audit/, and decision.md.
The CLI can be invoked from any supported AI tool via slash‑commands (e.g., ~/.claude/commands/.md), as described in README.md.
Real‑World Use
A dev team using Claude Code can embed the following snippet in their agent prompt:
When a user asks for a design suggestion, run: /q1-hypothesize "{{userquery}}" /q2-verify /q3-validate /q4-audit /q5-decide
The resulting .quint/decision.md becomes part of the repository’s documentation, allowing future reviewers to see which hypothesis was chosen and why without digging through chat logs.
Code Health & Issues
Tests – Medium – 10 Go test files (test.go) cover the FSM, DB migrations, and assurance calculator, showing reasonable coverage. CI – Low – GitHub Actions (.github/workflows/ci.yml) runs go test ./... on push; the pipeline passes but lacks lint or static‑analysis steps beyond golangci-lint config in src/mcp/.golangci.yml. License – Low – SPDX license header is present (LICENSE), no hidden proprietary code. Error handling – Medium – DB layer (src/mcp/db/store.go) returns raw errors without wrapping; callers often ignore them (, = store.Save(...)). This could obscure runtime failures. Concurrency – Low – The server (src/mcp/internal/fpf/server.go) starts a single HTTP listener; no explicit goroutine safety concerns are visible, but the SQLite store is accessed without transaction boundaries in some paths. Documentation – Low – Core commands are documented in markdown files under src/mcp/cmd/commands/; however, the README does not list flags for init or explain the JSON schema of .mcp.json. Adding a --help output or schema file would reduce onboarding friction.
The Bottom Line
quint-code provides a concrete, auditable workflow for AI‑assisted coding decisions, backed by a Go implementation, test suite, and CI. It is ready for teams that already use Claude Code, Cursor, Gemini, or Codex and need a traceable reasoning layer. Minor gaps—limited linting, sparse error handling, and incomplete CLI documentation—are easy to address; they do not undermine the core functionality. Suitable for medium‑to‑large engineering groups that value decision provenance more than a minimalist toolchain.