README.md
May 11, 2026 · View on GitHub
faf-cli v6.6
The Trophy Edition
Persistent Project Context for AI.
Define once. Run anywhere.
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 aproject.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
fafis shorthand forfaf-cli auto— same behavior, fewer keystrokes.
Nelly Never Forgets
Run faf with no arguments:
v6.6 — The Trophy Edition
Until now we have had 85% as a recommended minimum. It's now 100%! 🏆 All or nothing.
AI gets its best shot at assisting you. Period.
We are able to do this because we can now get you to 100% on virtually any app-type.
FAF Init > Auto > Go = 100%.
faf sync locks MD ↔ FAF with 100% 🏆 — anti-hallucination, pro-code.
(Adding about — the 20th app-type — made the ladder hit a score. How no-score became a score. Fitting, because v6.6 is when that score became the only one we recommend.)
Receipts → CHANGELOG
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
# Your own project
bunx faf-cli init # Create .faf
bunx faf-cli auto # Zero to 100% in one command
bunx faf-cli go # Interactive interview to gold code
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 are honest interim states on the way to Trophy, not endpoints.
| Tier | Score | Status |
|---|---|---|
| 🏆 Trophy | 100% | AI never has to guess |
| ★ Gold | 99%+ | 1 slot from Trophy |
| ◆ Silver | 95%+ | Close — keep going |
| ◇ Bronze | 85%+ | Interim — keep going |
| ● Green | 70%+ | Interim — keep going |
| ● Yellow | 55%+ | AI flipping coins |
| ○ Red | <55% | AI working blind |
| ♡ White | 0% | No context at all |
Sync
bi-sync: .faf ←── 8ms ──→ CLAUDE.md (free forever)
tri-sync: .faf ←── 8ms ──→ CLAUDE.md ↔ MEMORY.md (Pro)
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, 26 command registrations
├── commands/ ← 26 command files (1 per command)
├── core/ ← Types, slots (33 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 # 408 tests, 42 files, ~13s
- WJTTC Build Resilience (13) — every regression class locked.
- WJTTC Kernel Stress (19) — WASM kernel boundary tests.
- e2e lifecycle — every command 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.
License
MIT — Free and open source
IANA-registered: application/vnd.faf+yaml
format | driven 🏎️⚡️ wolfejam.dev