faf-cli
_{CONTEXT, versioned.}

The context every AI coding agent reads — authored from your repo, never guessed.

One .faf file → AGENTS.md · CLAUDE.md · GEMINI.md · .cursorrules,
detected from your real stack, scored, and versioned with your code. No drift. No re-explaining.

133k+ downloads · see faf.one/downloads for latest stats · IANA-registered · Anthropic-merged (#2759)

⭐ Bookmarks it for you, helps other devs find it too.

FAF defines. AGENTS.md instructs. AI codes.

project/
├── package.json     ← npm reads this
├── project.faf      ← AI reads this
├── README.md        ← humans read this
└── src/

Every building requires a foundation. FAF is AI's foundational layer.

You have a package.json. AI needs you to add a project.faf. Done.

Git-Native. project.faf versions with your code — every clone, every fork, every checkout gets full AI context.
No setup, no drift, no re-explaining.

---

Install

bunx faf auto                 # Bun — zero install, fastest path
npx faf auto                  # npm — works everywhere
brew install wolfe-jam/faf/faf-cli && faf auto   # Homebrew (auto-taps)

faf with no arguments shows your project's score; faf auto detects and fills.

---

Quick Start

# ANY GitHub repo — one shallow clone, no install, 2 seconds
bunx faf-cli git https://github.com/facebook/react

# Your own project
bunx faf-cli init              # Create .faf
bunx faf-cli auto              # Fill every tech slot from the repo, then score
bunx faf-cli go                # Interactive interview to gold code

---

Nelly Never Forgets

Run faf with no arguments:

faf-cli dogfoods itself — project.faf is source DNA; CLAUDE.md and GEMINI.md are authored from it via faf. AGENTS.md is the BETTER ops briefing (hand-kept for agents; faf export --agents still authors AGENTS.md for other repos).

---

Commands

Command	What it does
faf init	Create project.faf from your local project
faf git <url>	Instant .faf from any GitHub repo (a shallow clone)
faf auto	Detect stack, fill every slot it can, score
faf go	Guided interview to fill the human-only slots
faf score	Check AI-readiness (0–100%)
faf export	Author AGENTS.md, CLAUDE.md, GEMINI.md, .cursorrules
faf sync	.faf → CLAUDE.md (pull: Trophy-gated backfill)
faf memory	.fafm soul ops — convert Claude memory, etch, recall, ls, show
faf diff / log	Semantic context diff + score timeline across git history
faf hooks --install	Pre-commit guard against context regression
faf compile / decompile	.faf → .fafb sealed binary; decompile shows a .fafb's sections as JSON
faf check	Validate a .faf file
faf recover	Rebuild .faf from an existing CLAUDE.md / AGENTS.md
faf show	Render project.faf to a browsable HTML page
faf formats	List supported stacks and formats

Run faf --help for the full command set and options.

Memory (.fafm) — new in 7.2.0

Portable agent memory in the IANA-registered .fafm format. Same INTEROP as claude-fafm-sdk 1.0.

# Claude Code memory dir → soul.fafm
faf memory convert ~/.claude/projects/.../memory -o soul.fafm

faf memory ls                    # ranked facts
faf memory recall "your query"   # deterministic filter + rank
faf memory etch "a durable fact" --id my-fact
faf memory show

What's New in v7.13.0 — The Co-Author Edition

You and your AI co-author project.faf — AI fills the tech facts from your repo, you write the 6Ws — and faf-cli only touches what it wrote: links can't lead it outside your project, a failed write keeps the original, and your comments, values and notes stay as you left them.

• faf writes its block, you write the rest. faf touches only its managed block and its own section. A file with no faf markers is always prefixed, never taken over, even one that starts with faf's old stamp.
• project.faf edits keep your file as written. Comments, exact values (1.10 stays 1.10), anchors and keys faf doesn't know all survive. An edit changes only what it changes, and a no-op writes nothing.
• If it's a fact, faf fills the slot. A typed None or N/A is an empty slot, and the app-type decides which slots count.
  • faf auto fills a tech slot only from a repo fact. With no fact, the slot stays empty; only project.type falls back to library, and says so on its line.
  • With no fact, your words stay in a slot the app-type uses, and that slot scores 0 until filled.
  • In a slot the app-type leaves out, faf auto writes slotignored (shown as N/A).
  • The 6Ws stay yours: faf never replaces your words there, and faf go asks for the empty ones.
• faf ai enhance is retired. project.faf isn't enhanced: tech slots come from repo facts, and the 6Ws come from you.
• Links and encodings are checked first. faf refuses, in one line, to write:
  • through a link that leaves the project;
  • into .git, beyond its own hook section and diff driver;
  • over a whole file faf didn't render;
  • over a file that isn't UTF-8.
• A whole file faf renders is replaced only when it's still exactly what faf wrote. project.html and the Server and A2A cards now carry a render hash. If you edited one, faf leaves it and says so; --force replaces it.
• One-time step when upgrading: faf can't tell whether a project.html, Server Card or A2A card written before 7.13 was edited. The first run that would change one refuses it once, and that run exits 1. Check the file for hand edits, then run the same command once with --force; after that faf recognises its own output.
• A failed write keeps the original. faf writes to a temp file and renames it into place, so a full disk or a killed process leaves your file as it was. A file you edit while faf is writing is left alone.
• Memory stays yours.
  • soul.fafm keeps its curated index, its facts and its comments, and etching an id that already exists merges into that fact.
  • Tri-sync (FAF_PRO=1) writes Claude Code's own memory file as one section on top, and Claude's notes stay.
• Detection stays inside the project. Turbo-Cat no longer reads parent folders, so a monorepo root's stack no longer leaks into a package.
• For builders. New exports: resolveInside, safeWriteFile, updateFafFile, writeClaudeMemory, FafDNAManager, authorFafFromRepo, registryTitle, isNonProjectRoot and scoreText. writeFaf on an existing file now merges; pass { replace: true } for the old overwrite.
• Node 22+. The engine floor matches CI (22 and 24).

Recent sprint

• 🤝 7.13.0 The Co-Author Edition
• 🧩 7.12.0 The Open Renderers Edition
• 🖥️ 7.11.0 The VS Code Edition
• 📚 7.10.0 The Full-Facts Edition
• 🌱 7.9.0 The Git-Flow Edition
• 🎬 7.8.0 The Projector Edition
• 🐦 7.7.0 The Swift Edition
• 💎 7.6.0 The Ruby Edition
• ☕ 7.5.1 The JVM Edition

---

Custom instructions

Your own rules for the AI — "use full words in identifiers," "use bun, not npm" — go in project.faf under ai_instructions.warnings. They land at the top of every AGENTS.md faf writes, verbatim and non-destructive.

→ How to add custom rules · docs.faf.one

---

Scoring

✪ Trophy 100% — all or nothing. From v6.6.0 onward, faf-cli recommends only Trophy. 100% on the FCL is what makes the layers above (MD instructions, Agents, AI tooling) work — sub-Trophy leaves gaps that AI guesses on. Sub-Trophy tiers (including Bronze 85) remain on the ladder as honest interim states — they are not deleted; we just no longer aim for 85 as the goal.

Tier	Score	Status
✪ Trophy	100%	AI never has to guess — target
★ Gold	99%+	1 slot from Trophy
◆ Silver	95%+	Close — keep going
◇ Bronze	85%+	On the ladder (was the old recommend-min; not the target)
● Green	70%+	Interim — keep going
● Yellow	55%+	AI flipping coins
○ Red	<55%	AI working blind
♡ White	0%	No context at all

One score, three glyphs: ✪ work (CLI · docs · receipts) · 🏆 social (X · blogs) · Trophy Mark PNG (brand). Source of truth: src/core/tiers.ts.

---

Sync

sync:      .faf  ──── 8ms ───→  CLAUDE.md   (pull: Trophy-gated backfill)
tri-sync:  .faf  ──── 8ms ───→  CLAUDE.md + Claude Code's MEMORY.md   (Pro: faf's block only; Claude's notes kept)

---

Docs

The full manual lives at docs.faf.one — facts for devs, faf-cli first. One-page overview: faf-cli.vercel.app.

• Getting started — install · run · use
• Custom rules — pin instructions your AI must follow

For a specific agent: Grok, xAI & Cursor 👀 · Claude Code 👀 · Bun 👀

---

Recent editions

Pivotal releases — full history in CHANGELOG.md:

• v7.1 — AGENTS.md — faf export --agents authors a complete, non-destructive AGENTS.md.
• v7.0 — GIT — context goes git-native: faf diff / log / hooks.
• v6.16 — Know Your Stack — every emitted file labels your stack identically.
• v6.15 — Copilot — faf export --copilot writes the file GitHub Copilot reads.
• v6.14 — Loop — faf loop drives any repo to ✪ 100% or the honest human wall.
• v6.7 — HTML — faf show renders a .faf to a browsable page. (FAF defines. AGENTS.md instructs. AI codes. HTML shows.)
• v6.6 — Trophy — 100% or nothing.
• v6.0 — Bun — ground-up rewrite; single portable binary, four platforms.

---

Compiled Binaries

Bun's single-file compiler produces standalone binaries — no runtime needed.

bun run compile                # Current platform
bun run compile:all            # darwin-arm64, darwin-x64, linux-x64, windows-x64

Ship faf as a single binary for CI/CD, Docker, or air-gapped environments.

---

Architecture

src/
├── cli.ts              ← Entry point (Commander registrations)
├── commands/           ← one file per faf subcommand
├── core/               ← Types, slots (Mk4), tiers, scorer, schema
├── detect/             ← Framework detection, stack scanner
├── interop/            ← YAML I/O, CLAUDE.md, AGENTS.md, GEMINI.md
├── ui/                 ← Colors (#00D4D4), display
└── wasm/               ← faf-scoring-kernel wrapper (Rust → WASM)

Toolchain: Bun (test, build, compile) · TypeScript (strict) · WASM (scoring kernel)

---

Testing

Robust. Reliable. Next-level WJTTC tested. — The Foundation Edition.

bun test                       # extensive WJTTC + e2e suite

• WJTTC Build Resilience — regression classes locked.
• WJTTC Kernel Stress — WASM kernel boundary tests.
• e2e lifecycle — commands in sequence.

Test reports in reports/.

---

Support

• GitHub Discussions — Questions, ideas, community
• Email: team@faf.one

If faf-cli has been useful, consider starring the repo — it helps others find it.

---

Citation

If you use faf-cli or the .faf / .fafm / .fafa formats in research or production, please cite the format papers:

Wolfe, J. (2025). Format-Driven AI Context Architecture: The .faf Standard for Persistent Project Understanding. Zenodo. https://doi.org/10.5281/zenodo.18251362

Wolfe, J. (2026). Permanent Memory and Instant Recall: The .fafm Standard for Multi-Profile AI Agent Memory. Zenodo. https://doi.org/10.5281/zenodo.20348942

Wolfe, J. (2026). Why Agents Need a Passport: .fafa — Portable Identity for the Agentic Era. Zenodo. https://doi.org/10.5281/zenodo.21951641

BibTeX

@article{wolfe2025faf,
  title     = {Format-Driven AI Context Architecture: The .faf Standard for Persistent Project Understanding},
  author    = {Wolfe, James},
  year      = {2025},
  month     = {nov},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.18251362},
  url       = {https://doi.org/10.5281/zenodo.18251362}
}

@article{wolfe2026fafm,
  title     = {Permanent Memory and Instant Recall: The .fafm Standard for Multi-Profile AI Agent Memory},
  author    = {Wolfe, James},
  year      = {2026},
  month     = {may},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.20348942},
  url       = {https://doi.org/10.5281/zenodo.20348942}
}

@article{wolfe2026fafa,
  title     = {Why Agents Need a Passport: .fafa — Portable Identity for the Agentic Era},
  author    = {Wolfe, James},
  year      = {2026},
  month     = {aug},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.21951641},
  url       = {https://doi.org/10.5281/zenodo.21951641}
}

License

MIT — Free and open source

IANA-registered: application/vnd.faf+yaml (Context Layer) · application/vnd.fafm+yaml (Memory Layer) · application/vnd.fafa+yaml (Agent Layer)

format | driven 🏎️⚡️ wolfejam.dev · faf.one/cli