Install & init (v8)

Install

One-line installer:

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

The installer fetches the latest tagged release for your platform, places the binary in a writable bin directory, usually ~/.local/bin, and links it onto your PATH. Where available, it also installs the optional haft-embed sidecar under ~/.haft/runtimes/haft-embed/current for local semantic recall.

The installer may also unpack the Open-Sleigh runtime used by haft harness run. Treat that as the optional alpha execution track. You do not need it to use the v8 reasoning, spec, MCP, or haft check workflows.

From source (Go ≥ 1.25):

git clone https://github.com/m0n0x41d/haft
cd haft
task install

Initialize a project

Inside the repository you want to onboard:

cd path/to/your/project
haft init

This creates:

.haft/ with project identity (.haft/project.yaml), workflow policy (.haft/workflow.md), and placeholder spec carriers.
.haft/specs/target-system.md — placeholder TargetSystemSpec with one parseable draft section.
.haft/specs/enabling-system.md — placeholder EnablingSystemSpec.
.haft/specs/term-map.md — empty TermMap awaiting load-bearing terms.
MCP server config + the 15 skills and slash commands for the chosen host agent.

The placeholders are intentionally status: draft. They reserve a parseable structure without claiming active product authority; onboarding promotes them as the human approves load-bearing claims.

Init flags

haft init            # Claude Code (default), global commands (~/.claude/commands/)
haft init --local    # Claude Code, project-local commands (.claude/commands/)
haft init --codex    # Codex CLI / Codex App
haft init --all      # Claude Code + Codex

# Experimental hosts (config flags exist while runtime + docs converge):
haft init --cursor
haft init --gemini
haft init --opencode

What init does per tool

The binary is the same; only the MCP config and command/skill install locations differ.

Tool	MCP config	Commands / prompts	Skills
Claude Code	`.mcp.json` (project root)	`~/.claude/commands/` (or `.claude/commands/` with `--local`)	`~/.claude/skills/` (15 skills)
Codex CLI / App	`.codex/config.toml`	`~/.codex/prompts/` (or `.codex/prompts/` with `--local`)	`~/.agents/skills/` (15 skills)

Project-scoped configs (.mcp.json, .codex/config.toml) use portable project-root paths, so they are safe to commit for shared repositories.

Cursor: after init, open Settings → MCP → find haft → enable the toggle. Cursor adds MCP servers disabled by default.

Verify readiness

Right after init the project is needs_onboard. That is expected: the placeholder specs are parseable but not authoritative yet.

haft spec check
# spec_sections: 2
# active_spec_sections: 0
# term_map_entries: 0
# Findings: spec_carrier_no_active_sections (target + enabling),
#           term_map_missing_term

That is expected. Drive onboarding next:

haft spec onboard --json     # see the next typed phase
# In Claude Code / Codex with the haft MCP plugin loaded:
/h-onboard

See Spec onboarding for the typed flow.

Supported host agents

Claude Code and Codex are the supported hosts — the bundled prompts and skills are tested against them. Cursor, Gemini CLI, and OpenCode have experimental config flags while their runtime and docs converge; they receive tool calls, but contracts may not match every detail this guide describes.

Upgrade from v7

Existing .haft/ data is forward-compatible. Re-run haft init in your project to pick up the v8 skills and command files; your .haft/decisions/*, problems/*, notes/*, and specs/* survive untouched. After re-init, restart your host agent so it re-reads the MCP tools/list response. See MIGRATION-v8.md for what was dropped.