faf

FAF defines. 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                      # Bun — zero install, fastest path
npx faf                       # npm — works everywhere
brew install faf-cli && faf   # Homebrew

faf is shorthand for faf-cli auto — same behavior, fewer keystrokes.

---

Nelly Never Forgets

Run faf with no arguments:

---

v6.0 — Built with Bun

v6 is a ground-up rewrite. All-in on Bun — same toolchain as Claude Code.

	Claude Code	faf-cli v6
Runtime	Bun	Bun (bunx)
Test	Bun	bun test
Build	Bun	bun build
Language	TypeScript	TypeScript
Compile	Bun bytecode	bun build --compile

408 tests in ~13s. 296KB bundle in 2.4s. Single portable binary, 4 platforms. npx backward-compatible.

26 commands. 408 tests. WJTTC-tested. 93% smaller than v5.

commands → interop → core → wasm

The WASM scoring kernel (faf-scoring-kernel 2.0.0) does the math. Bun does the delivery.

---

Commands

#	Command	One-liner
1	faf init	Create .faf from your local project
2	faf git <url>	Instant .faf from any GitHub repo — no clone
3	faf auto	Zero to 100% in one command
4	faf go	Guided interview to gold code
5	faf score	Check AI-readiness (0-100%)
6	faf sync	.faf ↔ CLAUDE.md (bi-sync, mtime auto-direction)
7	faf compile	.faf → .fafb binary — sealed, portable, deterministic
8	faf decompile	.fafb → JSON
9	faf export	Generate AGENTS.md, .cursorrules, GEMINI.md
10	faf check	Validate .faf file
11	faf edit	Edit .faf fields inline
12	faf convert	Convert .faf to JSON
13	faf drift	Check context drift
14	faf context	Generate context output
15	faf recover	Recover .faf from CLAUDE.md / AGENTS.md
16	faf migrate	Migrate .faf to latest version
17	faf search	Search slots and formats
18	faf share	Share .faf via URL
19	faf taf	Generate TAF test receipt
20	faf demo	Demo walkthrough
21	faf ai	AI-powered enhance & analyze
22	faf pro	Pro features & licensing
23	faf conductor	Conductor integration
24	faf formats	Show supported formats
25	faf info	Version and system info
26	faf clear	Clear cached data

Run faf --help for full options.

---

Quick Start

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