Skip to content
/
Tier B A8 Cross-runtime harness

faf-cli

faf-cli · Wolfe-Jam/faf-cli · ★ 29 · last commit 2026-05-26

Primitive shape 1 total
Commands 1
00

Summary

faf-cli — Summary

faf-cli is a TypeScript/Bun CLI for the .faf (Foundational AI Format) file — an IANA-registered media type (application/vnd.faf+yaml) for persistent AI project context. The .faf file versions with the codebase in git, provides a 0-100% "AI-readiness" score, and bi-syncs with CLAUDE.md/AGENTS.md. The v6.7 "HTML Edition" added faf show to render the .faf file as a human-visible HTML page — "FAF defines. MD instructs. AI codes. HTML shows."

Problem it solves: AI tools re-discover project context on every session, wasting tokens and producing inconsistent results. The .faf file defines the project's identity ("6 W's": who, what, where, why, when, how) in a structured YAML format that versions with git — every clone, fork, or checkout gets full AI context automatically.

Distinctive trait: IANA registration. The .faf format has an officially registered MIME type (application/vnd.faf+yaml) and a companion research paper (DOI on Zenodo). A WASM scoring kernel (faf-scoring-kernel 2.0.0) runs deterministic 0-100% scoring. The format has a "Trophy 100%" target as the only recommended score since v6.6.

Target audience: Developers who want AI context that travels with the code. "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."

Differs from seeds: No seed parallel — this is the only framework in the corpus that pursues a formal standards track (IANA registration, Zenodo DOI paper). Most similar to agent-os (Archetype 4 — markdown scaffold for AI context) but faf-cli goes further: structured YAML format (not markdown prose), bi-directional sync, binary compilation (.fafb), WASM scoring, and an HTML render layer. Where agent-os ships opinionated Anthropic standards, faf-cli ships a neutral format specification.

01

Overview

faf-cli — Overview

Origin

Published by Wolfe-Jam on GitHub as faf-cli. 29 stars, 4 forks, MIT license. Last commit: 2026-05-26 (active). Language: TypeScript (Bun runtime). npm package: faf-cli. Homebrew tap: Wolfe-Jam/faf.

Philosophy

"FAF defines. MD instructs. AI codes. HTML shows."

"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."

"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."

"Eliminates 91% context re-discovery tax — define once, AI remembers forever."

Standards Track

Version History

  • v6.7 (current): "HTML Edition" — faf show renders project.faf to HTML
  • v6.6: "Trophy Edition" — 100% score target becomes the only recommended score
  • v6.0: Ground-up rewrite in Bun; 93% smaller bundle, 408 tests in ~13s
  • v5 and earlier: npm/legacy

FAF DNA System

The .faf-dna file tracks the birth of a project's FAF context, including:

  • Birth date, birthDNA hash, projectDNA
  • Version history with per-version scores and growth tracking
  • Recovery pointers (backup CLAUDE.md path)
  • Growth milestones ("Birth 🐣", etc.)
  • Certificate identifier (FAF-2026-CLIX-KQPK format)

6 W's of Context

FAF defines project context through six questions: who (audience), what (purpose), where (deployment), why (value), when (history), how (methods). This structured decomposition ensures completeness.

02

Architecture

faf-cli — Architecture

Distribution

  • Type: npm package + Homebrew formula + Claude Code plugin
  • Package: faf-cli on npm
  • License: MIT
  • Language: TypeScript (Bun runtime)
  • Bundle: Single portable binary, 4 platforms (from bun build --compile), 296KB

Install Methods

bunx faf                         # Bun — zero install, fastest
npx faf                          # npm — works everywhere
brew install faf-cli && faf      # Homebrew
npm install -g faf-cli           # Global install

Directory Tree (project-level files)

project/
├── project.faf        ← AI reads this (YAML + 6 W's + score metadata)
├── .faf-dna           ← version history, birth cert, growth tracking
├── .faf-state.json    ← sync state (last sync timestamp, bi_sync status)
├── .taf               ← TAF test receipt (WJTTC-tested flag)
├── .fafignore         ← patterns to exclude from context scan
├── CLAUDE.md          ← bi-synced FROM project.faf
├── .cursorrules       ← exported from project.faf
└── .gemini/           ← Gemini context

Plugin Structure (Claude Code)

.claude-plugin/
└── plugin.json   # name: "faf", version: "6.6.1"
                  # description: persistent project context, IANA-registered

Key Files

  • project.faf — the canonical context source (YAML, IANA media type application/vnd.faf+yaml)
  • .faf-dna — project "birth certificate" with DNA hash and version history
  • .faf-state.json — bi-sync state tracking (last_claude_sync, bi_sync: active/inactive)

WASM Scoring Kernel

faf-scoring-kernel 2.0.0 — handles scoring math in WebAssembly. Embedded in the Bun bundle. Deterministic, no network calls.

Required Runtime

  • Bun (preferred) or Node.js (fallback via npx)
  • No Claude Code required for CLI usage (plugin optional)

TAF (Test Attestation Framework)

.taf file generated by faf taf — a test receipt proving the project.faf was validated via WJTTC (WolfeJam Technical Testing Certification). Adds "battle-tested" signal.

03

Components

faf-cli — Components

CLI Commands (26)

# Command Purpose
1 faf init Create .faf from 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 format 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

File Formats

Format Description
.faf YAML project context (canonical) — IANA application/vnd.faf+yaml
.fafb Binary compiled context — sealed, portable, deterministic
.fafm FAF memory format — IANA application/vnd.fafm+yaml
.faf-dna JSON version history + birth certificate
.faf-state.json JSON sync state
.taf Test Attestation Framework receipt

Claude Code Plugin

  • Plugin name: faf
  • Registers /faf command in Claude Code
  • Purpose: run faf score from within Claude Code to check AI-readiness

No Skills, No Hooks, No Subagents

The Claude plugin only registers a single command (/faf). No lifecycle hooks, no skills, no subagents.

05

Prompts

faf-cli — Prompt Excerpts

Excerpt 1: project.faf — The Canonical Context Format

project:
  name: Project
instant_context:
  tech_stack: Unknown
metadata:
  last_claude_sync: 2026-01-07T14:59:11.733Z
  bi_sync: active
human_context:
  who: developers
  what: creates AI Context for AI assistants like Claude
  where: Terminal, IDEs
  why: AI needs context to perform well
  when: on new projects and add to older ones
  how: npm or homebrew
  context_score: 100
  success_rate: 100%

Prompting technique: 6-W structured context decomposition. Rather than free-form markdown prose, the .faf format forces the author to answer six structured questions (who/what/where/why/when/how). This provides consistent, machine-parseable context that can be scored deterministically. The context_score: 100 and success_rate: 100% fields serve as internal quality signals embedded in the file itself.

Excerpt 2: CLAUDE.md (faf-cli's own CLAUDE.md) — FAF-generated example

<!-- faf: faf-cli v6 | TypeScript | cli | CLI for the `.faf` format — persistent AI
context that versions with your code, and (v6.7, The HTML Edition) renders
human-visible on-demand via `faf show`. IANA-registered media type: `application/vnd.faf+yaml`. -->
<!-- faf: claim=project.faf | family=FAF -->

# CLAUDE.md — faf-cli v6

## What This Is

CLI for the `.faf` format — persistent AI context that versions with your code.

## Stack

- **Language:** TypeScript

## Context

- **Who:** Developers and teams using AI coding assistants
- **What:** Persistent AI Context Standard — project DNA for AI. IANA-registered.
- **Why:** Eliminates 91% context re-discovery tax — define once, AI remembers forever
- **Where:** npm registry, Homebrew, GitHub
- **When:** Production since September 2025, v6.0 March 2026
- **How:** bunx faf-cli auto, then project.faf versions with your code

*STATUS: BI-SYNC ACTIVE — 2026-05-18T02:01:43.463Z*

Prompting technique: HTML comment metadata injected into CLAUDE.md. The <!-- faf: ... --> comments carry machine-readable metadata (format family, canonical source, doc type) that can be parsed by tools while remaining invisible to humans reading the markdown. The "STATUS: BI-SYNC ACTIVE" footer proves the file was generated by faf, not hand-written, enabling validation.

09

Uniqueness

faf-cli — Uniqueness & Positioning

Differs From Seeds

No seed parallel exactly — faf-cli is the only framework in the corpus pursuing a formal standards track (IANA registration, Zenodo DOI papers). Most similar to agent-os (Archetype 4 — structured markdown for AI context) but fundamentally different: agent-os ships opinionated standards content in markdown prose; faf-cli ships a neutral YAML format specification with a WASM scoring kernel, binary compilation, bi-directional sync, and an HTML visualization layer. The "project.faf versions with the code in git" principle is faf-cli's core claim — more analogous to package.json than to CLAUDE.md.

The AGENTS.md vs AGENT.md Schism — faf-cli Position

faf-cli faf export generates AGENTS.md (OpenAI convention), .cursorrules (Cursor), and GEMINI.md (Google). It does not generate AGENT.md (Sourcegraph Amp convention). The README notes Anthropic approval, suggesting Claude-ecosystem alignment.

The Standards Bet

faf-cli is making a bet that AI context will become a standardized format (like package.json for npm projects), not a tool-specific file. The IANA registration is the most credible signal of this ambition in the corpus. No other framework has pursued this path.

Observable Failure Modes

  • The IANA registration and "Anthropic-approved" claims are marketing signals — adoption requires tool vendors to actually parse .faf files, which doesn't happen automatically
  • Bi-sync via mtime is fragile — any tool that touches either file without updating mtime could silently corrupt sync direction
  • Trophy 100% requirement since v6.6 may create pressure for "technically 100% but informationally poor" scores if the scoring rubric has exploitable dimensions
  • The .faf-dna birth certificate and growth tracking features add complexity without clear agent-facing utility

Most Novel Feature

faf git <url> — instant .faf generation from any GitHub repo without cloning. The repo is analyzed remotely (likely via GitHub API) to produce an initial context file. This is the fastest onboarding path in the corpus.

04

Workflow

faf-cli — Workflow

Quick Start Flow

Step Command Artifact
Create context faf init or faf auto project.faf
Score faf score 0-100% AI-readiness
Sync to CLAUDE.md faf sync CLAUDE.md updated from project.faf
Export to other tools faf export AGENTS.md, .cursorrules, GEMINI.md
HTML visualization faf show project.html (opens in browser)

Trophy Path (v6.6+)

faf init → faf auto → score = 100% (Trophy 🏆)

Only Trophy (100%) is recommended since v6.6. Sub-Trophy scores are "honest interim states on the way to Trophy, not endpoints."

Bi-Sync Flow

project.faf ←→ CLAUDE.md (mtime-based auto-direction)
project.faf → AGENTS.md (export only)
project.faf → .cursorrules (export only)
project.faf → GEMINI.md (export only)

faf sync uses file modification time to determine direction — whichever file is newer wins. The .faf-state.json tracks last_claude_sync and bi_sync: active.

Phase-to-Artifact Map

Phase Artifact
init project.faf
auto project.faf at 100%
score Score output (stdout)
sync CLAUDE.md
export AGENTS.md, .cursorrules, GEMINI.md
show project.html
compile .fafb (binary)
taf .taf receipt

Approval Gates

None. All commands are non-interactive (except faf go which is a guided interview).

06

Memory Context

faf-cli — Memory & Context

State Storage

File Purpose Format
project.faf Canonical project context YAML
.faf-dna Version history + birth certificate JSON
.faf-state.json Bi-sync state (last sync timestamp, active/inactive) JSON
.fafb Binary compiled context (sealed/portable) FAF binary

Bi-Directional Sync

faf sync synchronizes between project.faf and CLAUDE.md in both directions, using file modification time (mtime) to determine which is newer and should be the source. The .faf-state.json tracks sync status.

Git-Native Versioning

project.faf is a standard git-tracked file — it versions with the code. Every clone, fork, or branch checkout brings the full AI context. No external database or service required.

Cross-Session Persistence

The .faf file provides cross-session context persistence by design: the AI tool reads it on every session start. Combined with bi-sync to CLAUDE.md, the context is always current.

DNA / Version Tracking

.faf-dna records:

  • Birth date + initial score
  • Version history (score per version + changes)
  • Growth tracking (total growth, days active, best day/week)
  • Milestones (Birth, Gold, Trophy)
  • Recovery pointer (original CLAUDE.md backup path)

Context Drift Detection

faf drift checks whether the project.faf has drifted from the codebase's actual state — indicating the file may need refreshing.

07

Orchestration

faf-cli — Orchestration

No multi-agent, no orchestration. Single-tool context format + CLI.

The faf conductor command suggests integration with a "Conductor" system, but details are not publicly documented beyond the command name.

Execution mode: one-shot CLI commands. No daemon, no continuous loop.

08

Ui Cli Surface

faf-cli — UI / CLI Surface

CLI Binary

Yes — faf (via npm, Homebrew, or Bun).

  • Name: faf (shorthand for faf-cli auto)
  • Type: Own runtime (Bun-compiled single binary, 296KB, 4 platforms)
  • Thin wrapper: No — full runtime with WASM scoring kernel
  • Subcommands: 26 (see 03-components.md)

HTML Visualization (v6.7)

faf show renders project.faf to a self-contained project.html and opens it in the browser. This is the "4th pillar" — allowing humans to review what the AI sees.

  • No server — generates a static HTML file
  • Trophy visualization — renders earned trophy if score is 100%, shows gaps if sub-trophy
  • On-demand — always shows current truth, never a stale snapshot
  • Public render API — generateProjectHtml is a library-accessible function

Claude Code Plugin

/faf command available in Claude Code via .claude-plugin/plugin.json.

Homebrew

brew tap Wolfe-Jam/faf
brew install faf-cli

mcpaas Badge

faf-cli is listed on mcpaas.live (MCP server discovery) — suggests Claude Code MCP integration (details not fully documented in public repo).

Related frameworks

same archetype · same primary tool · same memory type

claude-mem (thedotmack) ★ 78k
A8 Cross-runtime harness

Background worker service captures every tool call as an observation, AI-compresses sessions, and auto-injects relevant past…

pi (badlogic/earendil) ★ 55k
A8 Cross-runtime harness

A minimal, hackable, multi-provider terminal coding agent that adapts to your workflows via npm-installable TypeScript Extensions…

Agent Skills (Addy Osmani) ★ 46k
A8 Cross-runtime harness

Encodes senior-engineer software development lifecycle as 23 auto-routed skills and 7 slash commands for any AI coding agent.

wshobson/agents Plugin Marketplace ★ 36k
A8 Cross-runtime harness

Single Markdown source for 83 domain-specialized plugins that auto-generates idiomatic artifacts for five AI coding harnesses.

TabbyML/Tabby ★ 34k
A8 Cross-runtime harness

Self-hosted AI coding assistant server (alternative to GitHub Copilot) with admin dashboard, RAG-based completions, and multi-IDE…

Compound Engineering ★ 17k
A8 Cross-runtime harness

Make each unit of engineering work compound into easier future work via brainstorm→plan→execute→review→learn cycles.