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.
115,000+ downloads across the FAF ecosystem · IANA-registered · Anthropic-merged (#2759)
⭐ A star helps other devs find faf-cli — despite the downloads, ~3 of 4 devs check stars.
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 wolfe-jam/faf/faf-cli && faf # Homebrew (auto-taps)
fafis shorthand forfaf-cli auto— same behavior, fewer keystrokes.
# 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 codeRun faf with no arguments:
faf-cli dogfoods itself — this repo's own AGENTS.md, GEMINI.md and CLAUDE.md are authored by
faffrom project.faf.
| Command | What it does |
|---|---|
faf init |
Create project.faf from your local project |
faf git <url> |
Instant .faf from any GitHub repo — no 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 |
Bi-directional .faf ↔ CLAUDE.md |
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 |
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.
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
🏆 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 |
🏆 and ✪ both mean 100% — the same top score, shown by surface: ✪ (the Proof Seal) on code surfaces — CLI, skills, docs, the hub — and 🏆 on social: posts, blogs, cards. You'll see both around for a while as the ✪ convention settles in.
bi-sync: .faf ←── 8ms ──→ CLAUDE.md
tri-sync: .faf ←── 8ms ──→ CLAUDE.md ↔ MEMORY.md
The full manual lives at docs.faf.one — facts for devs, faf-cli first.
- Getting started — install · run · use
- Custom rules — pin instructions your AI must follow
For a specific agent: Grok, xAI & Cursor 👀 · Claude Code 👀 · Bun 👀
Pivotal releases — full history in CHANGELOG.md:
- v7.1 — AGENTS.md —
faf export --agentsauthors a complete, non-destructiveAGENTS.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 --copilotwrites the file GitHub Copilot reads. - v6.14 — Loop —
faf loopdrives any repo to 🏆 100% or the honest human wall. - v6.7 — HTML —
faf showrenders a.fafto a browsable page. (FAF defines. MD instructs. AI codes. HTML shows.) - v6.6 — Trophy — 100% or nothing.
- v6.0 — Bun — ground-up rewrite; single portable binary, four platforms.
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 # 880 tests, 75 files, ~18s- 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.
If you use faf-cli or the .faf / .fafm 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
@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}
}MIT — Free and open source
IANA-registered: application/vnd.faf+yaml (Context Layer) · application/vnd.fafm+yaml (Memory Layer)
format | driven 🏎️⚡️ wolfejam.dev · faf.one/cli
