Home: faf.one/cli
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:
FAF is to Context what Git is to Versions.
Git gave your code diff, log, blame, hooks, CI. v7.0 gives your context the same — project.faf is now a git-native artifact:
faf diff— semantic context diff + score delta between any two refs (85% ● → 100% 🏆)git diffspeaks .faf —faf diff --install-drivermakes nativegit diff/log -p/showrender the deltafaf log— the score timeline across history (Proof-Over-Time)faf hooks --install— pre-commit guard: warn, or--strictblock, on a context regressionfaf git owner/repo --ref <tag>— instant, versioned, scored context from any repo
Purely additive — a safe upgrade. (One change: faf git now refuses to overwrite an existing project.faf — pass --force.)
FAF knows your stack — and now labels it identically in every file it writes: CLAUDE.md, AGENTS.md, copilot-instructions.md, GEMINI.md, .cursorrules.
faf export --all # CLAUDE.md · AGENTS.md · copilot-instructions.md · GEMINI.md · .cursorrulesFAF knows your stack — all 33 canonical slots now carry their display label in the registry, so api_type → API, cicd → CI/CD, frontend → Framework, the same way in every emitted file. GEMINI.md and .cursorrules were raw-key dumps; now they read like the rest. And .github/copilot-instructions.md gets a ground-up Copilot-grade rewrite — a prose overview, a ## Build & run command section, GitHub-spec framing. Copilot enhancements, and more.
FAF now writes the file GitHub Copilot reads.
faf export --copilot # → .github/copilot-instructions.md (every Copilot surface reads it)
faf git owner/repo # instant scored .faf from any GitHub repo (now injection-hardened)faf export --copilot emits GitHub Copilot's repository-wide instruction file — the widest-surface one, read by default across web chat, code review, VS Code, JetBrains, the CLI, and the coding agent. faf git is now hardened against URL command injection (no-shell execFileSync + a strict allowlist). Shipped with an exemplary WJTTC Git suite that adopts the full five tiers — BRAKE · ENGINE · AERO · TYRE · PIT.
faf loop drives any repo to 🏆 100% or the honest human wall — sourcing every slot it can with provenance, asking only what only you know, never inventing.
faf loop # init → auto → score, then ask only the human-only gapsThe loop sources what detection can, then stops at one of three honest terminals: done (🏆 100%), needs-human (it asks only the slots only you can answer), or stuck (it sourced everything sourceable and nothing's left for a human to add). It never fabricates a slot to reach 100% — sourced 6Ws now carry provenance ({value, source, confidence}), so every seeded value is a confirm-or-edit suggestion, never an auto-confirmed guess.
faf now understands Dart and Flutter projects. Content-aware pubspec.yaml classification — Flutter app vs reusable package · Dart server (Serverpod / Dart Frog / Shelf) / CLI / MCP — pure Dart stays Dart. The single-source engine faf-python-sdk and the MCPs compose, parity-tested across languages.
faf auto # reads pubspec.yaml → Dart/Flutter into project.fafA pubspec alone no longer means "Flutter": faf reads the dependencies and classifies — a Flutter app, a reusable package, a Dart server, a CLI, or a Dart MCP server. The detection knowledge lives in one spec (dart-detection.json) that faf-cli, faf-python-sdk, and the MCPs all share.
faf-cli is now the single source for the registry _meta — it emits the one.faf/context block every FAF MCP server composes: registryMeta/registryName/fafContextBlock, one deterministic projection, byte-identical, end-to-end across every surface, verifiable by sha, re-derivable instantly on-demand.
import { registryMeta, registryName } from 'faf-cli';
serverJson.name = registryName(faf); // → one.faf/<name>, derived from project.homepage
serverJson._meta = registryMeta(faf); // nests one.faf/context under publisher-provided (4 KB cap)Honest-first: the block carries { faf, mediaType, iana, deterministic, generated } — no baked score. One emitter, every door, byte-identical.
faf bench --submit posts your cold-vs-grounded receipt to the public ledger — the context bench goes public, one command. Run the grounding benchmark, then submit the full pair receipt:
faf bench --submitThe benchmark stops being a private number and becomes a shared, verifiable receipt on the public ledger. Also new: relentlessContext / assembleFreshFaf and the buildTableOf8 interview keystone join the public API.
Every FAF MCP composes single-source engines, never reimplements them. Turbo-Cat (the ~200-format knowledge base) and the bench engine join the public API, alongside scoring and the 6Ws Interview:
import { turboCatScan, deriveQuestionSet, publicQuestions, gradeAnswers, buildReceipt } from 'faf-cli';- Turbo-Cat composed —
turboCatScan/turboCatSlots: per-format breakdown + stack signature, sourced-only, deterministic, pure read. The MCPs retire their hardcoded format maps. - Bench composed — derive questions from any
.faf(the answer key stays server-side viapublicQuestions), grade mechanically, emit the✪receipt. One grading engine, byte-identical everywhere. ✪= one convention — parity · trust · bench all emit sha256-over-canonical-projection receipts any third party can re-derive.
Grounding becomes a first-class primitive: faf bench proves it, the 6Ws Interview single-sources it, faf refresh keeps it.
faf bench— the AI-grounding benchmark. Cold vs with-faf, two numbers (answers right, tokens burned), and the.fafis the answer key — grading is mechanical, the receipt is a verifiable✪sha256. A low cold score is an alarm bell: you are hemorrhaging tokens and the AI is guessing at what you're building.faf bench→ protocol,faf bench questions→ hand them to any AI,faf bench grade answers.json --cold|--faf→ the pair.- The 6Ws Interview, exported — the 8-question core (name + goal + the six Ws) plus the stack interview now ship as the public API (
SIX_WS_INTERVIEW,questionForSlot,interviewForMissing). One registry; every consumer (CLI, MCPs, UIs) asks the same questions. Question drift is dead. faf refresh— the re-ground: re-score the live.faf, measure drift vs the DNA baseline (drift: 43% ↑ 55% (+12)), keep an existing.fafbfast tier compiled current, record the journey.drift → refresh → re-grounded.
We rendered a .faf. 🔥 The day we saw FAF.
A major development — not a new flag, a new way to see what your AI
works from. A .faf was always machine-readable. Now it is
human-visible.
faf show
What: one verb renders your current project.faf to a
self-contained project.html and opens it — score, tier, the 6 W's,
the stack, in any browser.
Why it matters: HTML shows on-demand — current truth, never a stale snapshot — visuals for human and team review. The same context your AI reads, now reviewable by people. Trophy renders the earned award; sub-Trophy renders the honest gaps — a map, not a verdict. Humans like visuals. We gave them one.
It is a cross-check: see what your AI sees, then improve what it is
working with at the root — the project.faf itself, not the
symptoms.
This is the 4th pillar:
FAF defines. MD instructs. AI codes. HTML shows.
faf show · faf export --html · a public render API
(generateProjectHtml) — one single-sourced renderer, no reinvention.
Receipts → CHANGELOG
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 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 |
880 tests in ~18s. 296KB bundle in 2.4s. Single portable binary, 4 platforms. npx backward-compatible.
32 commands. 880 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🏆 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 (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 # 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