Installation

Install the binary

curl -fsSL https://haft.tools/install.sh | bash

This downloads the tagged 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 through your AI tool's MCP integration. 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.

Claude Code and Codex are the supported hosts in v8. Cursor, Gemini CLI, and OpenCode configs are experimental; 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

# 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	`.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.