MCP governance layer for Claude Code and Codex

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 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 parses fenced yaml spec-section blocks, checks required structural fields, validates known carrier shapes, and confirms the term-map carrier parses. It makes no L2 semantic judgment, no LLM review, and no L3 runtime claim.

---

What is Haft?

Haft sits between the human principal, the coding agent, and the repository. It brings the versioned FPF source into the agent's working context, keeps project reasoning connected to the code it governs, and makes durable records only when later work needs to rely on them.

Haft is not a coding agent or an AI documentation generator. It is the handle that keeps problems, options, human decisions, specifications, work authority, and evidence connected as the project changes.

What Makes It Different

• Source-native FPF delivery — agents can retrieve the versioned FPF source with provenance instead of relying on a Haft-owned substitute catalog.
• Reliance-bearing memory — ordinary local reasoning may stay in chat; records enter the project graph for handoff, replay, authority, automation, evidence, or another explicit downstream reliance.
• Kernel gates, not prompt-only discipline — skills carry the procedure; the MCP kernel validates required fields, parity gaps, missing evidence, and authority boundaries server-side.
• Reasoning fused with code — haft_query can show the decisions and invariants governing a file or symbol while the agent reads or changes it.
• Evidence decays — old proof is not treated as forever current; Haft surfaces stale claims and drift for review.
• Human authority stays explicit — agents can frame, compare, verify, and prepare records, but binding decisions and commissions require the human principal.
• Agent guidance is built in — status, method cards, spec checks, and structured errors tell the agent what is missing.

Three surfaces, one artifact graph

Haft is consumed through three surfaces over one .haft/ artifact graph:

• Skills in your agent. Capability skills may trigger from the current operator request; h-decide may route a direct unambiguous binding request, while h-commission still requires manual invocation.
• CLI (haft artifact, haft decision, haft spec, haft memory, haft commission, ...) — direct manual access to the current command families.
• MCP server (haft serve) — programmatic access for any LLM agent over the Model Context Protocol

The kernel MCP server is the cross-host enforcement surface: it validates arguments server-side and returns structured errors for FPF violations (missing required fields, parity gaps, weakest-link omissions, predictions without verify_after, and so on).

Skills carry the procedure; the kernel carries the gates. The same graph also gives agents retrieval over project-local reasoning: notes for small facts, decision records for authority, problem cards for open work, spec sections for target/software-system shape, MethodRuns for execution discipline, and evidence for verification.

FPF source and project-local application

The FPF source defines the available concepts and methods. Haft pins and indexes that source, carries it into the host agent, and supplies project-local records and gates where later work needs them. Retrieval is not application, evidence, approval, or performed work.

FPF is relation-first: the order of text, graph edges, cards, skills, or a demonstrative walkthrough does not by itself prescribe causal, temporal, method, or performed-work order. Such order exists only when an explicit, separately governed causal claim, U.MethodDescription, WorkPlan, or work relation states it. This does not make FPF acausal. Causal reasoning remains available, but causality must be carried as a claim rather than inferred from layout.

Planning remains a separate current task. A U.WorkPlan may state dependencies and execution order whenever planning is the concern; an FPF source lookup, application record, or reasoning capability does not prescribe that order. A WorkCommission carries bounded execution authority and must not stand in for the plan. Decision binding requires a direct unambiguous operator request; execution-authority grants through h-commission remain manual-only.

haft fpf query|lookup|inspect and haft_query(action="fpf", mode="concern|lookup|inspect", ...) expose the versioned source as addressable publication units. Concern retrieval reports observable authored-phrase, heading/keyword, and role-local FTS grounds; lookup tries exact identity before returning compact candidates; inspect is exact-only. Source roles (practical_use_card, toc_row, preface, pattern_body, pattern_section, pattern_scope) control progressive disclosure. Candidates are not selected patterns, and their order is not a causal or work order.

Maintaining the pinned FPF publication

Start with task fpf-refresh-check. It fetches and resolves one exact upstream candidate, builds private temporary artifacts, and writes .context/fpf-refresh/latest-report.json without changing the checked-out source, embedded database, integration lock, typed-memory candidate, or specs. The report has one closed result:

Result	Meaning	Next action
no_change	Candidate and current publication are the same.	Nothing to apply.
apply_ready	The technical compatibility checks admit the candidate.	Run task fpf-refresh.
review_ready	A complete candidate built and verified, while parser, semantic, Query-behavior, token-budget, or expectation findings need later review.	task fpf-refresh prints a prominent warning, applies the fresh source baseline, and retains every finding for downstream review.
candidate_rejected	The required source publication is missing, its structure is unsupported, or no deterministic and internally coherent source/index publication could be built and verified.	Adapt the source parser/compiler or repair the integrity failure, then check again.

task fpf-refresh repeats the check, pins the resolved candidate SHA, and recoverably applies the coherent source, database, and generated integration-lock publication for both apply_ready and review_ready. review_ready is an auditable semantic-delta classification, not a veto on adopting fresh FPF as Haft's source baseline. Query/token fixture drift is also review_ready: the command prints a large FPF REFRESH REVIEW WARNING, keeps the exact diagnostics and reproduction commands in the report, and continues the recoverable apply. Exact PatternID/query-smoke drift, token fixtures, and semantic compatibility gaps belong here when the generic source-query runtime and derived publication are still coherent. A new recognizable result-label family is indexed with its exact raw source, flagged as degraded parser review, and does not veto refresh. Such findings may block release or query-quality claims, but they do not leave Haft on stale FPF source. Applying the candidate records no semantic approval and grants no release authority. A hard rejection is reserved for the absence of a complete structurally supported candidate — for example a missing required publication, source structure too incomplete to derive the required roles/categories, a derived source-unit projection below 50% of the preceding verified count, failed derivation, or failed source/DB/lock integrity verification. The apply also rebases only the repo-owned Local-Practice compiled memory basis and FPF-Spec.md source pins, then proves that the carrier parses, compiles, seals, verifies, and links against the fresh basis. task fpf-refresh finishes with the exact read-only integration verification. After a low-level recovery, run task fpf-verify. If an apply is interrupted, keep the receipt unchanged and use task fpf-refresh-resume to continue or task fpf-refresh-restore to restore its exact predecessor; never delete or hand-edit the receipt.

Generated hashes, counts, and compatibility results remain distinct from human-reviewed semantic and changelog claims. None of these commands commits, binds a decision, changes a SpecSection lifecycle, changes the active project-memory model, installs or restarts Haft, runs P13/P14, pushes, tags, or releases.

Fused code and reasoning graph

Explore accepts exactly one input shape: an exact symbol, or a bounded concern query. The concern route returns advisory candidates and never selects a code identity from rank alone.

haft graph explore --symbol PublishIndexEpoch --view working --json
haft graph explore --query "where is the index epoch published?" --view working --json

The equivalent MCP calls are haft_query(action="explore", symbol="PublishIndexEpoch") and haft_query(action="explore", query="where is the index epoch published?"). Both surfaces execute one canonical ExploreEnvelope and use the same JSON encoder. working is bounded, score-free, and omits retrieval and per-edge provenance. trace adds bounded provenance plus an opaque replay basis; diagnostic adds retrieval and traversal internals. A replay after the index, request, or canonical result changes returns replay_mismatch.

Use Explore when area or flow orientation is current. Before a non-mechanical edit to governed code, use code_context or impact on the actual target. Purely mechanical work may abstain explicitly. Code-graph orientation and typed-memory orientation are separate; neither substitutes for the other.

Code-graph indexing is automatic and shared by concurrent haft serve processes for the same project. Several host tasks can remain open: one server publishes a changed source epoch while followers stay responsive and recheck the completed result. A request that cannot establish freshness within its bounded wait reports the retained complete epoch as degraded, or reports the index unavailable when no complete epoch exists. Distinct projects continue indexing independently; no single-server setup or manual cleanup is required.

What changed in v8 and v9

v8 dropped the standalone interactive agent (haft agent), its coding-agent TUI, and the desktop wrappers. v9 completes that boundary by removing the built-in haft run and haft harness executors and the bundled Open-Sleigh BEAM runtime. haft board, the governance CLI, MCP server, and skills remain. Haft records runner-neutral WorkCommissions; execution belongs to the host agent or another separately operated runner.

Upgrading from the published v8.1.0 release, or still migrating a v7 project? See MIGRATION-v8.md for backup, forward-upgrade, host restart, and rollback boundaries.

How It Works

Twelve MCP tools

Tool	What it does
haft_note	Non-binding facts, observations, caveats, and rationale with typed anchors, validation, and optional freshness
haft_problem	Frame problems, declare comparison dimensions with indicator roles
haft_solution	Explore variants with diversity check, compare under parity
haft_decision	Decision contracts: invariants, claims, evidence, baseline lifecycle
haft_refresh	Lifecycle management for every artifact kind
haft_query	Project search/status, code graph, source-native FPF query/lookup/inspect, and typed-memory resolve/neighborhood/recall
haft_method	Task-local SWE MethodRun cards: pull gates before non-trivial work, close with evidence or waivers
haft_commission	Runner-neutral WorkCommission authority and lifecycle records
haft_spec_section	Typed SpecSection lifecycle projection over project SQL editions; FPF source compatibility is assessed separately; manual CLI gates approve, rebaseline, or reopen baselines
haft_onboard	Read setup status, prepare a non-binding initial profile review, or prepare an explicitly requested predecessor-pinned sco