Get Started
Install quint-code, pick a mode, make a decision you'll remember.
Installation
Step 1: Install the binary
$ curl -fsSL https://quint.codes/install.sh | bash
Step 2: Initialize in your project
The binary is the same for all tools. The init flag tells quint-code where to write the MCP config — each tool looks for it in a different place.
$ quint-code init
$ quint-code init --cursor
$ quint-code init --gemini
$ quint-code init --codex
$ quint-code init --all
Where MCP config goes
Each tool expects its MCP server config in a different location. Init handles this automatically:
| Tool | MCP Config | Note |
|---|---|---|
| Claude Code | .mcp.json | Auto-detected |
| Cursor | .cursor/mcp.json | Enable in Settings → MCP |
| Gemini CLI | ~/.gemini/settings.json | Global config |
| Codex / Air | .codex/config.toml | Trust project in Codex settings |
Init creates a .quint/ directory in your project with markdown projections for code review.
Slash commands and the /q-reason skill are installed globally for your tool.
Existing project? Run /q-onboard after init — the agent scans your
codebase for existing ADRs, architecture docs, and decision patterns worth capturing.
First time? Ask the agent to explain:
/q-reason explain how to work with quint-code effectively
The agent knows all Quint commands and will walk you through the workflow in context of your project.
Decision modes
Pick the depth that matches the decision's weight. The agent auto-selects when you use /q-reason.
/q-reason — Let the agent decide the depth
Describe your problem. The agent frames it, generates alternatives, compares them fairly, and records the decision — all in one command. It auto-selects tactical, standard, or deep mode based on blast radius and reversibility.
Full cycle — Maximum rigor
For architectural decisions where you want to drive each phase. Define what you'll compare on before you see the options. Each dimension gets a role — constraint, target, or observation. Then compare fairly with parity enforcement.
/q-frame Define signal, constraints, optimization targets, acceptance criteria /q-char Set comparison dimensions with roles — constraint, target, observation /q-explore Generate distinct alternatives with weakest link — diversity checked automatically /q-compare Fair comparison — parity enforced, dimensions cross-checked, gaps warned /q-decide FPF E.9 decision contract — problem frame, decision, rationale, consequences The tool warns if you skip steps — but never blocks. Missing characterization? Compare still works, just without safety checks.
Quick cycle — Three steps for reversible decisions
Library picks, API design, caching strategy — things with blast radius under 2 weeks. Skip characterization and formal comparison. Frame, explore, decide.
/q-frame What's broken, what constraints, what does solved look like /q-explore 2-3 alternatives with tradeoffs /q-decide Pick one, record why, set expiry /q-note — Micro-decisions on the fly
The agent captures micro-decisions automatically when it notices them in conversation. You discover a hidden invariant, pick a library, choose an approach — it's recorded with rationale before you move on. No rationale, no record. Conflicts with active decisions are flagged. Auto-expires in 90 days so your knowledge base doesn't rot.
The Decision Record
Every /q-decide produces a Decision Record following the
FPF E.9 four-component structure. It's an engineering contract, not a document.
1. Problem Frame
Why are we talking about this? Signal, constraints, and acceptance criteria — pulled automatically from the linked ProblemCard. Context first, always.
2. Decision (the contract)
What was chosen. Invariants (what MUST hold). Pre/post-conditions (checklists). Admissibility (what is NOT acceptable). This is the contract a new engineer reads 6 months later.
3. Rationale
Why this, not that. Comparison table of all variants with verdicts. Weakest link identified. Evidence requirements declared. The reasoning is auditable.
4. Consequences
Rollback plan with triggers and steps. Refresh triggers — when to re-evaluate. Affected files. Blast radius. Everything needed to undo or revisit.
Decision Records are stored as git-tracked markdown files in .quint/decisions/ and indexed in SQLite for search and lifecycle management.
Key concepts
R_eff (WLNK)
Effective Reliability — a computed trust score (0–1) for every decision. Equals the weakest piece of evidence, never the average. Factors in congruence level (same context vs different) and freshness decay. One expired benchmark drops the whole score.
Evidence Decay
Evidence has expiry dates. A benchmark from 6 months ago scores 0.1 (weak, not absent). Decisions with R_eff below 0.5 auto-surface in stale scans. Below 0.3 — flagged "AT RISK." Graduated epistemic debt: most overdue items shown first.
Indicator Roles
Every comparison dimension gets a role: constraint (hard limit — must satisfy), target (what you're optimizing), or observation (watch but don't optimize — Anti-Goodhart). Missing a constraint in comparison? Strong warning. Missing an observation? Informational.
Parity
Same inputs, same scope, same budget for all options — or the comparison is junk. The tool cross-checks your comparison against characterization dimensions, warns on asymmetric scoring, and generates a per-dimension parity checklist automatically.
Diversity Check
When you explore variants, the tool checks if they're genuinely distinct — not three flavors of the same idea. Jaccard similarity above 50% triggers: "do they differ in kind, not degree?"
Archive Recall
When you frame a problem or explore variants, the tool searches your past decisions and notes. "You decided on caching strategy 3 months ago" — surfaced at the moment it matters, not when you remember to search.
Problem Lifecycle
Problems move through three states automatically: Backlog (framed, no work started), In Progress (variants being explored), Addressed (decision made). No manual status management — derived from artifact links.
Lifecycle management
Decisions aren't static. /q-refresh manages the lifecycle of
all artifact types — notes, problems, decisions, portfolios.
/q-refresh Scan for staleness — expired validity, degraded evidence (R_eff < 0.5), AT RISK items. waive Still valid? Extend with justification. Default: +90 days. reopen Needs re-evaluation? Creates new ProblemCard with lineage from old decision. supersede Replaced by a better decision? Link old to new. deprecate No longer relevant? Archive it. The tool prompts a refresh scan if more than 5 days pass without one — ensuring the feedback loop stays closed and stale decisions don't accumulate silently.
Other commands
/q-status Dashboard — active decisions, stale items, problem lifecycle (Backlog / In Progress / Addressed), recent notes. /q-search Full-text search across all decisions, problems, and notes. /q-problems List all problems with Goldilocks signals — readiness score and complexity counts. /q-onboard Discover existing project knowledge. Recommended for brownfield projects. When to use
Use quint-code for
- Architectural decisions with long-term consequences
- Unfamiliar territory — new tech, new patterns, new domains
- Decisions you'll need to explain or revisit later
- Problems with multiple valid approaches and real tradeoffs
- Anything you'd regret not documenting in 3 months
Skip it for
- Bug fixes with obvious solutions
- Trivially reversible choices
- Time-critical emergencies
- Personal preference (tabs vs spaces)