haft

FPF project memory and governance for AI-assisted engineering.

Haft is a local governance layer for AI coding agents. It gives your agent a durable project memory: what problem is being solved, which options were compared, which decisions the human made, what evidence supports them, and what has gone stale. Small, reversible reasoning can stay in conversation; results that later work must rely on become typed project records.

Haft is built on the First Principles Framework (FPF) by Anatoly Levenchuk. FPF is a rigorous architecture for thinking about systems, and it is not small. Haft is the practical handle: it brings the versioned FPF source into your agent's working context and adds the project-local skills, MCP gates, and memory needed to use it in engineering work.

Install

curl -fsSL https://raw.githubusercontent.com/m0n0x41d/haft/main/install.sh | bash

For a project that has not used Haft before, initialize it once. Bare haft init opens an interactive multi-select when stdin and stdout are terminals; no host is preselected. Scripts and CI must name their intent explicitly:

haft init                    # Interactive host multi-select (TTY only)
haft init --core-only        # Project core/ledger, no host carriers
haft init --claude           # Claude MCP + skills + CLAUDE.md section
haft init --claude --local   # Claude integration with repo-local skills
haft init --codex            # Codex MCP + skills + AGENTS.md section
haft init --codex --local    # Codex integration with repo-local skills
haft init --codex --mcp-only # Compatibility: Codex MCP config only
haft init --agents           # Global .agents/skills only
haft init --agents --local   # Repo-local .agents/skills only
haft init --codex --agents   # Codex integration; shared skill target coalesces
haft init --grok             # Grok CLI project MCP + skills
haft init --hermes           # Hermes MCP + external skills directory
haft init --zed              # Zed global MCP context server
haft init --agy              # Google Antigravity MCP + shared skills
haft init --all              # Full Claude + Codex integrations
haft init --all --mcp-only   # Claude + Codex MCP configs only

Any explicit init flag skips the menu and executes its declared behavior. Bare non-interactive invocation fails before writing files instead of guessing a host or waiting for terminal input. --mcp-only is a compatibility modifier: it requires an explicit host flag or --all and suppresses that host's skills and managed instruction section.

Codex publishes its transformed skills to ~/.agents/skills, or project .agents/skills with --local, as part of the full Codex integration. --agents addresses the same location as an independent skills-only target without MCP or instruction publication. It may compose with host flags; with --codex, the identical .agents/skills projection is coalesced into one write rather than treated as two competing targets. --all means exactly the full Claude and Codex integrations; it does not add a second independent --agents target.

For an already initialized project, install the new binary and fully restart or reconnect the coding-agent host. A new haft serve process automatically applies only migration boundaries that the release explicitly marks as startup-safe. The current chain covers 57 -> 58 and 58 -> 59; Haft first publishes a verified 0600 SQLite snapshot beside the project ledger at each boundary it crosses. A current database is a no-op. Re-running haft init is not routine database maintenance.

If startup reports a manual migration boundary, use the exact fallback command from that diagnostic:

haft project migrate --project-root /absolute/project/root --project-id qnt_........

It verifies the exact project binding, shares the same migration lease as haft serve and haft init, and changes no agent-host config, skill, instruction, hook, or package carrier. Future-schema, missing-binding, integrity, and stale WAL/SHM diagnostics have different recovery paths; do not replace them with a generic migration run.

Claude Code and Codex are the stable supported hosts. Grok, Pi, Hermes, Zed, Antigravity, Cursor, Gemini CLI, and OpenCode remain experimental or legacy adapters with additional config flags (--grok, --pi, --hermes, --zed, --agy, --cursor, --gemini, --opencode). Please report host-specific issues with a PR or issue.

Grok: use haft init --grok (optionally --local). Native project .grok/config.toml takes precedence over Claude/Cursor compat MCP sources, so a stale global haft entry in ~/.claude.json no longer shadows the project server. Reload MCP in Grok (/mcps → r) or start a new session after init.

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

What init does per tool

The binary is the same; host adapters differ in MCP config, transformed skill location, and instruction carrier. Re-init replaces recognized legacy Haft skills and updates only the content between <!-- haft:start --> and <!-- haft:end --> in project instruction files. Content outside those markers remains project-owned. A foreign file colliding with a desired Haft-owned skill path fails before writes instead of being overwritten.

Tool MCP config Skills Project instructions

Claude Code (stable) .mcp.json ~/.claude/skills/ or .claude/skills/ with --local managed section in CLAUDE.md

Codex CLI / App (stable) .codex/config.toml ~/.agents/skills/ or .agents/skills/ with --local managed section in AGENTS.md

Agent skill bundle (--agents) n/a ~/.agents/skills/ or .agents/skills/ with --local none

Grok CLI (experimental) .grok/config.toml (mcp_servers.haft) ~/.grok/skills/ or .grok/skills/ with --local host adapter

Hermes (experimental) ~/.hermes/config.yaml (or $HERMES_HOME/config.yaml; profile via --profile) generated Hermes-adapted skills through skills.external_dirs host adapter

Zed (experimental) ~/.config/zed/settings.json (context_servers.Haft) n/a none

Antigravity (experimental) ~/.gemini/config/mcp_config.json (mcpServers.haft) ~/.gemini/skills/ or .gemini/skills/ with --local host adapter

Project-scoped configs (.mcp.json, .codex/config.toml, .grok/config.toml) use portable project-root paths, so they are safe to commit for shared repositories. Zed and Antigravity settings are global and may start MCP/context servers outside the workspace cwd. haft init --zed writes HAFT_PROJECT_ROOT and HAFT_EXPECTED_PROJECT_ID for the project where you ran init. haft init --agy writes serve --project-root <root> --expected-project-id <id> args so the Antigravity entry does not depend on cwd or env propagation. Re-run the host-specific init command in another project to point the global host entry there.

Local footprint

Haft is local-first, but it is not a zero-footprint prompt pack. haft init creates markdown carriers in .haft/ and a project SQLite database under ~/.haft/projects/<id>/. Those databases are where Haft keeps the structured artifact graph, baselines, indexes, and runtime state that agents query through CLI/MCP.

The Rust haft-embed sidecar is retained as an optional compatibility component for older semantic-recall paths; core v9 governance does not depend on it. If one of those paths uses it, Haft may start a shared local EmbeddingGemma process and cache models under ~/.haft/; a warm sidecar can reasonably take around 1-2 GB of RAM depending on platform, model, and workload. If the sidecar is absent or disabled, the compatibility path falls back to keyword/graph recall. Set embedding.provider: none in ~/.haft/config.yaml to keep that path off.

v9 no longer ships Elixir, OTP, BEAM, or the Open-Sleigh runtime. During a successful upgrade the installer removes only the exact legacy managed path ~/.haft/runtimes/open-sleigh/current. It preserves user-owned ~/.open-sleigh/ data and the independent haft-embed runtime.

How to Start

FPF is powerful and genuinely complex. You do not need to learn it all before Haft becomes useful.

Install Haft, run haft init for your agent, and keep working normally. When a concern benefits from FPF, the agent can retrieve the relevant source and use the smallest applicable method. Call /h-reason when you want a deliberate source-supported reasoning pass.

The narrower skills are independent application surfaces, not stages in a mandatory workflow:

• /h-frame — clarify the real problem and acceptance criteria

• /h-explore — generate genuinely different solution variants

• /h-compare — compare options under explicit parity rules

• /h-decide — route a direct operator request for a binding decision

• /h-verify — check whether a past decision still holds

• /h-status — read the compact project cockpit

Haft makes actual gates explicit: when a human decision is needed, when evidence has gone stale, when spec drift needs review, and when execution needs an authorized plan or commission. It does not infer a universal next step from the order of skills or artifacts.

Existing codebase that has never been initialized with Haft? Run haft init --core-only. A complete, non-truncated, supported singleton detector result is admitted as origin=detector_default; Haft then installs only the specification and MethodPack carriers applicable to that scope. Mixed, multiple-scope, insufficient, truncated, or manually reviewed bases remain profile-review work, and init never changes an existing canonical profile. A later direct, unambiguous operator r