AGENTS.md — faf-cli

CLI for IANA-registered .faf + .fafm (application/vnd.faf+yaml · vnd.fafm+yaml) — TypeScript · Bun-native since v6 · npm package faf-cli v7.2.0 (The Memory Edition).

Setup & build

bun install
bun run build    # clean → bun build cli+index → tsc (dist/)
bun run dev      # bun src/cli.ts

Run the tests

bun run test     # bun test --timeout=120000 — must pass before a change is done
bun run lint     # eslint src/**/*.ts

Ship-adjacent (when touching build output or publish path):

bun run check:no-hardcode   # fail if machine paths leaked into dist/

Where things live

Path	Role
src/cli.ts	CLI entry (Commander)
src/index.ts	Library entry
src/commands/	One file per faf subcommand (init, score, export, sync, memory, …)
src/fafm/	.fafm library (Soul, fromClaudeDir) — INTEROP with claude-fafm-sdk 1.0
src/core/	Domain engines (slots, scorer, types, schema) — compose, don’t fork
src/detect/	Stack / project detection
src/interop/	Context emitters (agents.ts, claude.ts, gemini.ts, …)
src/wasm/	Bridge to faf-scoring-kernel (Rust→WASM) — scoring lives here, not reimplemented in TS
src/ui/	Terminal UI helpers
package.json	Scripts, bin (faf / faf-cli → dist/cli.js)
project.faf	Project DNA (keep version/goal honest when they change)

Conventions

• Bun-native — use bun, not npm, for install/run/test in this repo.
• TypeScript strict + ESM ("type": "module") — obey tsconfig.json and ESLint; don’t restyle by hand.
• Domain-model first — single-source engines in src/core/; compose them from commands; never reimplement scoring in TypeScript (use the WASM kernel).
• Wording (product copy): FAF authors (never “generates”); never guessed (not “not guessed”); never write Guaranteed (any form) — free software.
• Match the style of the surrounding file.

Guardrails

• Always OK: read the tree · bun run test · bun run lint · bun run build · edit under src/ with tests.
• Ask first: dependency adds/upgrades · deletions · publish / release / tag · changes to scoring kernel integration · dual-publish (faf ↔ faf-cli) path.
• Never: force-push · push straight to main (branch and open a PR) · commit secrets · hand-run npm publish (releases go through /pubpro only) · reimplement scoring outside faf-scoring-kernel / src/wasm/.

Definition of Done

Done when:

1. bun run lint exits 0
2. bun run test passes
3. If you touched the build/publish surface: bun run build and bun run check:no-hardcode pass
4. Change is on a branch with a clear conventional commit (feat:, fix:, chore:, …)

When stuck

Ask a clarifying question, propose a short plan, or open a draft PR with notes — do not push large speculative changes to main.

Commit & PR

• Conventional Commits preferred.
• One logical change per PR when practical.
• If you change package.json scripts, layout under src/, or publish gates — update this file in the same PR.

The context every AI coding agent reads — authored from your repo, never guessed.

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.

Over 100k downloads · see faf.one/downloads for latest stats · 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 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 wolfe-jam/faf/faf-cli && faf   # Homebrew (auto-taps)

faf is shorthand for faf-cli auto — same behavior, fewer keystrokes.

---

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

---

Nelly Never Forgets

Run faf with no arguments:

faf-cli dogfoods itself — project.faf is source DNA; CLAUDE.md and GEMINI.md are authored from it via faf. AGENTS.md is the BETTER ops briefing (hand-kept for agents; faf export --agents still authors AGENTS.md for other repos).

---

Commands

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 memory	.fafm soul ops — convert Claude memory, etch, recall, ls, show
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.

Memory (.fafm) — new in 7.2.0

Portable agent memory in the IANA-registered .fafm format. Same INTEROP as claude-fafm-sdk 1.0.

# Claude Code memory dir → soul.fafm
faf memory convert ~/.claude/projects/.../memory -o soul.fafm

faf memory ls                    # ranked facts
faf memory recall "your query"   # deterministic filter + rank
faf memory etch "a durable fact" --id my-fact
faf memory show

What's New in v7.6.0 — The Ruby Edition

Content-aware Ruby — Gemfile alone ≠ Rails. Pure gems stay pure gems.

• Gems + layout — Rails · Sinatra · Roda · Grape · Hanami · MCP · CLI · library (static parse — does not execute Gemfile).
• Still shipping — JVM (7.5.x) pom/gradle alone ≠ type · C# (7.4.0) .csproj alone ≠ type · Go (7.3.0) go.mod alone ≠ backend.

Dart/Flutter — knowledge v2 in 7.2.1

pubspec ≠ Flutter — pure Dart stays Dart. Same content-aware detection as the Dart Edition. 7.2.1 refreshes the single-source knowledge table: Riverpod annotation, Flutter Hooks, Beamer, Routemaster, Jaspr, Relic, and more MCP package names — still one classifier, composed by the MCPs.

---

Custom instructions

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

---

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 (including Bronze 85) remain on the ladder as honest interim states — they are not deleted; we just no longer aim for 85 as the goal.

Tier	Score	Status
✪ Trophy	100%	AI never has to guess — target
★ Gold	99%+	1 slot from Trophy
◆ Silver	95%+	Close — keep going
◇ Bronze	85%+	On the ladder (was the old recommend-min; not the target)
● Green	70%+	Interim — keep going
● Yellow	55%+	AI flipping coins
○ Red	<55%	AI working blind
♡ White	0%	No context at all

One score, three glyphs: ✪ work (CLI · docs · receipts) · 🏆 social (X · blogs) · Trophy Mark PNG (brand). Source of truth: src/core/tiers.ts.

---

Sync

bi-sync:   .faf  ←── 8ms ──→  CLAUDE.md
tri-sync:  .faf  ←── 8ms ──→  CLAUDE.md ↔ MEMORY.md

---

Docs

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 👀

---

Recent editions

Pivotal releases — full history in CHANGELOG.md:

• v7.1 — AGENTS.md — faf export --agents authors a complete, non-destructive AGENTS.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 --copilot writes the file GitHub Copilot reads.
• v6.14 — Loop — faf loop drives any repo to ✪ 100% or the honest human wall.
• v6.7 — HTML — faf show renders a .faf to 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.

---

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 (Commander registrations)
├── commands/           ← one file per faf subcommand
├── core/               ← Types, slots (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                       # extensive WJTTC + e2e suite

• WJTTC Build Resilience — regression classes locked.
• WJTTC Kernel Stress — WASM kernel boundary tests.
• e2e lifecycle — commands 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.

---

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 · faf.one/cli