Installation

Install the binary

curl -fsSL https://quint.codes/install.sh | bash

This downloads the latest release for your platform (macOS/Linux, arm64/amd64) and places it in ~/.local/bin/. Make sure this directory is in your PATH.

Initialize in your project

You must run init in every project. haft runs as an MCP plugin inside your AI tool — not as a standalone agent. Each project needs its own MCP config with a unique project ID and path. A global MCP config pointing to a single project will silently send all artifacts to that project, even when you're working in a different directory.

CLI tools (Claude Code, Gemini CLI, Codex CLI) always launch from the current directory, so this mostly works transparently. IDE-based tools (Cursor, Windsurf) may behave differently — if something goes wrong, run init in the correct directory and restart the tool.

cd into your project directory and run init with the flag for your AI tool:

# Claude Code (default if no flag)
haft init

# Cursor
haft init --cursor

# Gemini CLI
haft init --gemini

# Codex CLI / Codex App
haft init --codex

# OpenCode (sst/opencode)
haft init --opencode

# JetBrains Air
haft init --air

# All tools at once
haft init --all

The flag matters. Each tool looks for its MCP config in a different location. Running haft init without a flag only configures Claude Code. If you use Cursor, you need --cursor.

Where MCP config goes

The binary is the same for all tools. Init writes the MCP server config to the location your tool expects:

Tool	MCP Config	Commands	Note
Claude Code	`.mcp.json`	`~/.claude/commands/`	Auto-detected
Cursor	`.cursor/mcp.json`	`~/.cursor/commands/`	Enable in Settings → MCP
Gemini CLI	`~/.gemini/settings.json`	`~/.gemini/commands/`	Global config
Codex / Air	`.codex/config.toml`	`~/.codex/prompts/`	Trust project in Codex
OpenCode	`opencode.json`	`~/.config/opencode/commands/`	Use `--local` for `.opencode/`

Cursor-specific setup

After running haft init --cursor, open Cursor Settings → MCP → find haft → enable the toggle. Cursor adds MCP servers as disabled by default.

Cursor also picks up Claude Code slash commands from ~/.claude/commands/, so commands like /h-reason may work even without --cursor. But the MCP connection (the tools backend) requires .cursor/mcp.json.

What init creates

Init creates a .haft/ directory in your project:

.haft/
├── project.yaml        # Project identity (unique ID, name)
├── decisions/          # Decision record markdown files
├── problems/           # Problem card markdown files
├── notes/              # Micro-decision markdown files
├── solutions/          # Solution portfolio markdown files
├── evidence/           # Evidence pack markdown files
└── refresh/            # Verification report markdown files

These markdown files are projections — human-readable copies of what's in the database. They're designed for code review: when you create a decision, a markdown file appears in your PR diff. Reviewers can see and comment on engineering decisions alongside code changes.

The database itself lives in ~/.haft/projects/{id}/ (not in your repo). The .haft/ directory contains only markdown and YAML — safe to commit.

Migrating from v5? If you have an existing .quint/ directory, haft init detects it and migrates everything automatically — renames the directory to .haft/, moves the database, preserves all artifacts. See Migration guide for details.

Verify it works

Open your AI tool in the project directory and type:

/h-status

You should see an empty dashboard. If you see an error about MCP connection, check that the MCP server is enabled in your tool's settings.

Next step

First steps — what to do after installation.