convez.ai
MCP Server
Wolfe-Jam

faf-cli

Wolfe-Jam/faf-cli

Ver no GitHub
BomPluginScore · de 0 a 100

Persistent Project Context for AI — IANA-registered .faf format. The CLI behind the Foundational Context Layer (FCL).

Instalação

$npx convez-ai Wolfe-Jam/faf-cli

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
44
Forks
5
Acompanhando
0
Saúde
100%
Último commit
há 1 dia
Versão
v8.10.0
Issues abertas
2
Contribuidores
3

README

A tradução para o português deste README ainda está na fila.

npm version FAF Trophy 100% IANA: vnd.faf+yamlIANA: vnd.fafm+yaml DOI: Context paperDOI: Memory paper

Home: faf.one/cli

FAF defines. MD instructs. AI codes.

FAF TAF CI Homebrew License: MIT project.faf

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:

faf


v6.7 — The HTML Edition

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


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 Codefaf-cli v6
RuntimeBunBun (bunx)
TestBunbun test
BuildBunbun build
LanguageTypeScriptTypeScript
CompileBun bytecodebun 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

#CommandOne-liner
1faf initCreate .faf from your local project
2faf git <url>Instant .faf from any GitHub repo — no clone
3faf autoZero to 100% in one command
4faf goGuided interview to gold code
5faf scoreCheck AI-readiness (0-100%)
6faf sync.faf ↔ CLAUDE.md (bi-sync, mtime auto-direction)
7faf compile.faf → .fafb binary — sealed, portable, deterministic
8faf decompile.fafb → JSON
9faf exportGenerate AGENTS.md, .cursorrules, GEMINI.md
10faf checkValidate .faf file
11faf editEdit .faf fields inline
12faf convertConvert .faf to JSON
13faf driftCheck context drift
14faf contextGenerate context output
15faf recoverRecover .faf from CLAUDE.md / AGENTS.md
16faf migrateMigrate .faf to latest version
17faf searchSearch slots and formats
18faf shareShare .faf via URL
19faf tafGenerate TAF test receipt
20faf demoDemo walkthrough
21faf aiAI-powered enhance & analyze
22faf proPro features & licensing
23faf conductorConductor integration
24faf formatsShow supported formats
25faf infoVersion and system info
26faf clearClear 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.

TierScoreStatus
🏆 Trophy100%AI never has to guess
★ Gold99%+1 slot from Trophy
◆ Silver95%+Close — keep going
◇ Bronze85%+Interim — keep going
● Green70%+Interim — keep going
● Yellow55%+AI flipping coins
○ Red<55%AI working blind
♡ White0%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


If faf-cli has been useful, consider starring the repo — it helps others find it.


Citation

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

BibTeX

@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}
}

License

MIT — Free and open source

IANA-registered: application/vnd.faf+yaml (Context Layer) · application/vnd.fafm+yaml (Memory Layer)

format | driven 🏎️⚡️ wolfejam.dev

Ver o original no GitHub

Bom para

Relacionados