haft

<img src="assets/banner.svg" alt="Haft" width="600">

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 57 -> 58 transition first publishes a verified 0600 SQLite snapshot beside the project ledger; 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 <ins>powerful</ins> 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 request may supersede only a current detector_default profile; onboarding status reports profile_override_eligible, and successful application appends a host_routed_operator_request admission. TargetSystemSpec is Required for every declared realization scope; an optional entity_reference strengthens exact EntityOfConcern memory and traceability but does not gate specification applicability or lifecycle. The bounded profile_change_prepare route remains available only when changing that relation is itself current, and is never a prerequisite for spec work. Onboarding ready covers only the canonical profile and structured project memory; it is not a spec-applicability, health, lifecycle, or release-readiness verdict.

Check spec carriers locally:

haft spec status
haft spec status --json
haft spec check
haft spec check --json
haft spec migrate
haft spec migrate --json # read-only state for agents and automation

haft spec status keeps two read-only results explicit: workflow.state reports the next onboarding lifecycle action, while health reports current structural, baseline, drift, and staleness findings. A terminal workflow state such as ready therefore does not erase health findings and is not a release readiness claim; use haft spec check --json for the full health report.

SoftwareSystemSpec describes the software that realizes the target system: its role, responsibility allocation, behavior, interfaces, constraints, and selected structure. Agent, commission, external-runner, and delivery policies are deliberately outside this spec. Development-version enabling-system.md carriers are migrated with one state-driven haft spec migrate command. Haft resolves the internal exact candidate itself, records semantic review on one invocation, performs the already reviewed migration on a later invocation, and continues a sealed recovery journal when needed. Humans never pass packet paths, hashes, refs, targets, or recovery modes.

haft spec check is deterministic L0/L1/L1.5 only: it