quint code

Abstract

Structured reasoning framework for Claude Code, Gemini, Cursor, and Codex — hypothesis-driven decision making with auditable evidence trails

The Problem

AI coding assistants pattern-match to the first plausible answer and discard the reasoning that produced it. Decisions live in ephemeral chat history, so a week later nobody — human or model — can reconstruct why a design choice was made or what evidence supported it. Quint Code addresses this by forcing a structured, hypothesis-driven reasoning loop and persisting every step as an auditable trail.

What This Does

Quint Code is a Go-based MCP server plus slash-command set that implements the First Principles Framework (FPF) — abduction (generate competing hypotheses), deduction (verify logic), induction (gather evidence), then audit and decide. It installs commands like /q1-hypothesize and /q2-verify into Claude Code, Cursor, Gemini CLI, and Codex CLI, and stores all state in a .quint/ directory backed by SQLite.

The core engine lives in src/mcp/internal/fpf/ (tools.go, fsm.go, projection.go, server.go), with persistence in src/mcp/db/ (store.go, query.sql.go) and an assurance calculator in src/mcp/assurance/calculator.go that computes reliability scores with evidence decay and cycle detection.

How It Is Wired

Execution starts at main in src/mcp/main.go, which routes through runServe (src/mcp/cmd/serve.go) into Start (src/mcp/internal/fpf/server.go:53), the MCP server loop that reaches 69 functions. All tool calls funnel through handleToolsCall (reaches 66 functions), which dispatches to handlers like SaveState, VerifyHypothesis, and CreateHolon.

The wiring is shallow: Start -> handleToolsCall -> SaveState reaches the database in three hops via f.DB.Exec, and runServe -> NewStore opens SQLite and the filesystem directly. The blast-radius leaders are Close (called from 42 places), setupTools (26), NewStore (23), and CreateHolon (21) — changes to these ripple widely. src/mcp/db/store.go is the hub (30 functions, called from 16 files); src/mcp/internal/fpf/tools.go is the only file that runs external commands in addition to file and DB I/O. No import cycles exist.

How To Use It

curl -fsSL https://raw.githubusercontent.com/m0n0x41d/quint-code/main/install.sh | bash
# or build from source:
git clone https://github.com/moses-y/quint-code
cd quint-code/src/mcp
go build -o quint-code .
sudo mv quint-code /usr/local/bin/

Run quint-code init in a project (flags: --claude, --cursor, --gemini, --codex, --all, --local), then start with /q0-init and /q1-hypothesize "Your problem...". Copy the FPF Glossary from CLAUDE.md into your agent rules for best results. Note the README's Codex caveat: per-project MCP config isn't supported, so re-run init --codex per project.

Real-World Use

A team evaluating a payment-webhook retry design runs /q1-hypothesize to generate competing approaches, /q2-verify to check each against constraints, and /q3-validate to test against evidence. Each decision lands in .quint/ with a hashed evidence trail (projection.go computes content hashes to detect tampering), queryable via /q-query and decayed via /q-decay. The docs/workflow_example/payment-webhooks.md walks this exact scenario.

Code Health & Issues

Static analysis (not opinion) found 8 findings: one high — duplicated code blocks: 33 repeated 6-line blocks across 11 files including src/mcp/cmd/init.go, src/mcp/internal/fpf/tools.go, and src/mcp/db/store.go; extract shared helpers. Four medium — deep nesting (max depth 6 in server.go), oversized files (query.sql.go at 951 lines, tools.go, tools_test.go), and high branching density (38 branch points over 133 lines in assurance/calculator.go). CI findings: High — pin codecov/codecov-action@v4, golangci-lint-action@v7, and upload-release-action@v2 to commit SHAs (tag-move supply-chain risk); Medium — declare least-privilege GITHUB_TOKEN permissions, enable Dependabot, add a dependency vulnerability scan; Low — set timeout-minutes on workflow jobs. Tests, CI, license, and lockfile are present; no committed secrets.

The Bottom Line

A sound, well-tested implementation of a genuinely useful idea: making AI reasoning auditable rather than trusting it. The duplicated code and dense control flow in the FPF layer will slow contributors, but the architecture is clean enough to absorb that. Best for teams already using Claude Code who want evidence-backed decision records on real engineering work.