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.
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.
Run faf with no arguments:
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.
| # | 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.
# 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| Tier | Score | Status |
|---|---|---|
| 🏆 Trophy | 100% | AI Optimized — Gold Code |
| ★ Gold | 99%+ | Near-perfect |
| ◆ Silver | 95%+ | Excellent |
| ◇ Bronze | 85%+ | Production ready |
| ● Green | 70%+ | Solid foundation |
| ● Yellow | 55%+ | AI flipping coins |
| ○ Red | <55% | AI working blind |
| ♡ White | 0% | No context at all |
bi-sync: .faf ←── 8ms ──→ CLAUDE.md (free forever)
tri-sync: .faf ←── 8ms ──→ CLAUDE.md ↔ MEMORY.md (Pro)
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-x64Ship faf as a single binary for CI/CD, Docker, or air-gapped environments.
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)
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/.
- GitHub Discussions — Questions, ideas, community
- Email: team@faf.one
If faf-cli has been useful, consider starring the repo — it helps others find it.
MIT — Free and open source
IANA-registered: application/vnd.faf+yaml
format | driven 🏎️⚡️ wolfejam.dev