FAF-CLI for Claude & Claude Code Developers

August 1, 2026 · View on GitHub

One command. Every agent in your session gets the same accurate, versioned context.

FAF-CLI (v7.1, "The AGENTS.md Edition") is the canonical tool for the .faf format: persistent, versioned, AI-readable project context. For Claude it does two things a hand-written file can't: it bi-syncs CLAUDE.md with a single scored source of truth (project.faf), and it exposes live FAF tools to Claude over MCP. Part of the FAF ecosystem — over 100k downloads; see faf.one/downloads for latest stats.

Quick start (zero-install)

bunx faf                     # auto-detect the stack, write project.faf, score it
bunx faf sync                # bi-sync .faf ↔ CLAUDE.md (edit either; the other follows)
bunx faf export --agents     # also emit AGENTS.md — Claude Code reads it too
bunx faf score               # AI-readiness score (target: Trophy 100%)

npx faf works too. Run faf sync on save, in a pre-commit hook, or in CI, and CLAUDE.md never drifts from the project it describes.

The doc hierarchy — where FAF fits

README.md    → prose for humans
CLAUDE.md    → prose for Claude
project.faf  → structure for any AI  ← the scored source the others project from

CLAUDE.md is Claude's instruction file. project.faf is the structured, scored source it's authored from — so instead of hand-maintaining prose that rots the moment the stack changes, you maintain one source and let FAF keep CLAUDE.md current.

Why this fits Claude Code

Claude Code reads CLAUDE.md (and AGENTS.md) at the start of every session. FAF makes those a projection of one scored source, not hand-kept files:

  1. Bi-directional sync — faf sync keeps .faf ↔ CLAUDE.md aligned with mtime auto-direction: edit CLAUDE.md and the .faf updates; edit the .faf and CLAUDE.md updates. No manual reconciliation, no drift.
  2. Non-destructive — FAF maintains a labeled block and preserves everything you wrote by hand.
  3. Scored, not guessed — faf score tells you whether Claude is starting from complete context or filling gaps by hallucination. Target the Trophy (100%) and every session starts from a full picture.
  4. Git-native — the .faf versions with your code, so context travels with the branch and matches the commit Claude is working on.

Live tools over MCP — claude-faf-mcp

Static files are the baseline; claude-faf-mcp is the live layer. It wires FAF into Claude Desktop and Claude Code so Claude can call FAF tools directly — score, validate, and context operations — instead of only reading Markdown. One .faf source; two surfaces (the file Claude reads, the tools Claude calls) that never disagree.

For CLAUDE.md maintainers & teams

  • Stop hand-editing — bunx faf once, then faf sync keeps CLAUDE.md honest as the stack evolves.
  • Onboarding — a new teammate or a fresh Claude session gets accurate context immediately, not a stale hand-written guess.
  • Remote work — faf git owner/repo pulls structured, scored context for any repo Claude needs to reason about, no clone required.
  • One source → many surfaces — change project.faf, and CLAUDE.md, AGENTS.md, and the MCP tools stay consistent.

Why it's a natural fit

FAF-CLI isn't another AI wrapper — it's the canonical, versioned, stack-aware source that CLAUDE.md should be authored from. The bi-sync means the file Claude reads can't quietly fall out of date, and the MCP server means Claude can act on live context, not just a snapshot. One command (bunx faf) turns any project into one Claude can actually understand — measurable, versioned, and consistent.

Links: faf.one · .faf format · faf-cli on npm · claude-faf-mcp on npm · IANA application/vnd.faf+yaml