{"id":35176676,"url":"https://github.com/wolfe-jam/faf-cli","last_synced_at":"2026-05-17T23:09:06.232Z","repository":{"id":312231167,"uuid":"1046716559","full_name":"Wolfe-Jam/faf-cli","owner":"Wolfe-Jam","description":"Persistent Project Context for AI — IANA-registered .faf format · universal CLI","archived":false,"fork":false,"pushed_at":"2026-05-09T05:14:32.000Z","size":37571,"stargazers_count":29,"open_issues_count":7,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-09T06:40:29.201Z","etag":null,"topics":["agents-md","ai","ai-context","claude","claude-code","cli","context-engineering","cursor","developer-tools","faf","file-format","gemini","grok","iana","mcp","nodejs","npm","project-dna","typescript","yaml"],"latest_commit_sha":null,"homepage":"https://faf.one","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Wolfe-Jam.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"wolfejam","custom":["mailto:team@faf.one"]}},"created_at":"2025-08-29T05:42:08.000Z","updated_at":"2026-05-09T05:13:39.000Z","dependencies_parsed_at":"2026-04-02T18:03:42.526Z","dependency_job_id":"3968e78f-fe27-430c-ad2f-fc790778fdd9","html_url":"https://github.com/Wolfe-Jam/faf-cli","commit_stats":null,"previous_names":["wolfe-jam/faf-cli"],"tags_count":61,"template":false,"template_full_name":null,"purl":"pkg:github/Wolfe-Jam/faf-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wolfe-Jam%2Ffaf-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wolfe-Jam%2Ffaf-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wolfe-Jam%2Ffaf-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wolfe-Jam%2Ffaf-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Wolfe-Jam","download_url":"https://codeload.github.com/Wolfe-Jam/faf-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wolfe-Jam%2Ffaf-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32917885,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-11T17:09:15.040Z","status":"ssl_error","status_checked_at":"2026-05-11T17:08:45.420Z","response_time":120,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents-md","ai","ai-context","claude","claude-code","cli","context-engineering","cursor","developer-tools","faf","file-format","gemini","grok","iana","mcp","nodejs","npm","project-dna","typescript","yaml"],"created_at":"2025-12-28T22:52:11.797Z","updated_at":"2026-05-17T23:09:06.227Z","avatar_url":"https://github.com/Wolfe-Jam.png","language":"TypeScript","funding_links":["https://github.com/sponsors/wolfejam","mailto:team@faf.one"],"categories":[],"sub_categories":[],"readme":"\u003c!-- faf: faf-cli | TypeScript | cli | CLI for the .faf format — IANA-registered AI context that versions with your code --\u003e\n\u003c!-- faf: doc=readme | canonical=project.faf | score=100 | family=FAF --\u003e\n\n\u003cdiv style=\"display: flex; align-items: center; gap: 12px;\"\u003e\n  \u003cimg src=\"https://www.faf.one/orange-smiley.svg\" alt=\"FAF\" width=\"40\" /\u003e\n  \u003cdiv\u003e\n    \u003ch1 style=\"margin: 0; color: #000000;\"\u003efaf-cli v6.7\u003c/h1\u003e\n    \u003cp style=\"margin: 2px 0 0 0; font-size: 0.85em; letter-spacing: 0.12em; opacity: 0.7; text-transform: uppercase;\"\u003e\u003cstrong\u003eThe HTML Edition\u003c/strong\u003e\u003c/p\u003e\n    \u003cp style=\"margin: 6px 0 0 0;\"\u003e\u003cstrong\u003ePersistent Project Context for AI.\u003c/strong\u003e\u003c/p\u003e\n    \u003cp style=\"margin: 0;\"\u003e\u003cstrong\u003eDefine once. Run anywhere.\u003c/strong\u003e\u003c/p\u003e\n  \u003c/div\u003e\n\u003c/div\u003e\n\n**FAF defines. MD instructs. AI codes.**\n\n[![FAF](https://mcpaas.live/badge/Wolfe-Jam/faf-cli.svg)](https://builder.faf.one)\n[![TAF](./badge.svg)](https://github.com/Wolfe-Jam/faf-taf-git)\n[![CI](https://github.com/Wolfe-Jam/faf-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/Wolfe-Jam/faf-cli/actions/workflows/ci.yml)\n[![NPM Downloads](https://img.shields.io/npm/dt/faf-cli?label=total%20downloads\u0026color=00CCFF)](https://www.npmjs.com/package/faf-cli)\n[![npm version](https://img.shields.io/npm/v/faf-cli?color=00CCFF)](https://www.npmjs.com/package/faf-cli)\n[![Homebrew](https://img.shields.io/badge/Homebrew-faf--cli-orange)](https://github.com/Wolfe-Jam/homebrew-faf)\n[![Website](https://img.shields.io/badge/Website-faf.one-orange)](https://faf.one)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Built with Bun](https://img.shields.io/badge/Built_with-Bun-f9f1e1?logo=bun)](https://bun.sh)\n[![project.faf](https://img.shields.io/badge/project.faf-inside-00D4D4)](https://github.com/Wolfe-Jam/faf)\n\n```\nproject/\n├── package.json     ← npm reads this\n├── project.faf      ← AI reads this\n├── README.md        ← humans read this\n└── src/\n```\n\n\u003e **Every building requires a foundation. FAF is AI's foundational layer.**\n\u003e\n\u003e You have a `package.json`. AI needs you to add a `project.faf`. Done.\n\n**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.\n\n---\n\n## Install\n\n```bash\nbunx faf                      # Bun — zero install, fastest path\nnpx faf                       # npm — works everywhere\nbrew install faf-cli \u0026\u0026 faf   # Homebrew\n```\n\n\u003e `faf` is shorthand for `faf-cli auto` — same behavior, fewer keystrokes.\n\n---\n\n## Nelly Never Forgets\n\nRun `faf` with no arguments:\n\n![faf](./nelly.png)\n\n---\n\n## v6.7 — The HTML Edition\n\n**We rendered a `.faf`. 🔥 The day we *saw* FAF.**\n\nA major development — not a new flag, a new way to *see* what your AI\nworks from. A `.faf` was always machine-readable. Now it is\nhuman-visible.\n\n```\nfaf show\n```\n\n**What:** one verb renders your *current* `project.faf` to a\nself-contained `project.html` and opens it — score, tier, the 6 W's,\nthe stack, in any browser.\n\n**Why it matters:** HTML shows **on-demand** — current truth, never a\nstale snapshot — **visuals for human *and team* review.** The same\ncontext your AI reads, now reviewable by people. Trophy renders the\nearned award; sub-Trophy renders the honest gaps — a map, not a\nverdict. Humans like visuals. We gave them one.\n\nIt is a **cross-check**: see what your AI sees, then improve what it is\nworking with **at the root** — the `project.faf` itself, not the\nsymptoms.\n\nThis is the **4th pillar**:\n\n\u003e **FAF defines. MD instructs. AI codes. HTML shows.**\n\n`faf show` · `faf export --html` · a public render API\n(`generateProjectHtml`) — one single-sourced renderer, no reinvention.\n\nReceipts → [CHANGELOG](./CHANGELOG.md)\n\n---\n\n## v6.6 — The Trophy Edition\n\nUntil now we have had 85% as a recommended minimum. **It's now 100%! 🏆 All or nothing.**\n\nAI gets its best shot at assisting you. **Period.**\n\nWe are able to do this because we can now get you to 100% on virtually any app-type.\n\n**FAF Init \u003e Auto \u003e Go = 100%.**\n\n`faf sync` locks MD ↔ FAF with 100% 🏆 — anti-hallucination, pro-code.\n\n(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.)\n\nReceipts → [CHANGELOG](./CHANGELOG.md)\n\n---\n\n## v6.0 — Built with Bun\n\nv6 is a ground-up rewrite. All-in on Bun — same toolchain as Claude Code.\n\n| | Claude Code | faf-cli v6 |\n|-|-------------|------------|\n| **Runtime** | Bun | Bun (`bunx`) |\n| **Test** | Bun | `bun test` |\n| **Build** | Bun | `bun build` |\n| **Language** | TypeScript | TypeScript |\n| **Compile** | Bun bytecode | `bun build --compile` |\n\n408 tests in ~13s. 296KB bundle in 2.4s. Single portable binary, 4 platforms. npx backward-compatible.\n\n26 commands. 408 tests. WJTTC-tested. 93% smaller than v5.\n\n```\ncommands → interop → core → wasm\n```\n\nThe WASM scoring kernel (`faf-scoring-kernel` 2.0.0) does the math. Bun does the delivery.\n\n---\n\n## Commands\n\n| # | Command | One-liner |\n|---|---------|-----------|\n| 1 | `faf init` | Create `.faf` from your local project |\n| 2 | `faf git \u003curl\u003e` | Instant `.faf` from any GitHub repo — no clone |\n| 3 | `faf auto` | Zero to 100% in one command |\n| 4 | `faf go` | Guided interview to gold code |\n| 5 | `faf score` | Check AI-readiness (0-100%) |\n| 6 | `faf sync` | `.faf` ↔ CLAUDE.md (bi-sync, mtime auto-direction) |\n| 7 | `faf compile` | `.faf` → `.fafb` binary — sealed, portable, deterministic |\n| 8 | `faf decompile` | `.fafb` → JSON |\n| 9 | `faf export` | Generate AGENTS.md, .cursorrules, GEMINI.md |\n| 10 | `faf check` | Validate `.faf` file |\n| 11 | `faf edit` | Edit `.faf` fields inline |\n| 12 | `faf convert` | Convert `.faf` to JSON |\n| 13 | `faf drift` | Check context drift |\n| 14 | `faf context` | Generate context output |\n| 15 | `faf recover` | Recover `.faf` from CLAUDE.md / AGENTS.md |\n| 16 | `faf migrate` | Migrate `.faf` to latest version |\n| 17 | `faf search` | Search slots and formats |\n| 18 | `faf share` | Share `.faf` via URL |\n| 19 | `faf taf` | Generate TAF test receipt |\n| 20 | `faf demo` | Demo walkthrough |\n| 21 | `faf ai` | AI-powered enhance \u0026 analyze |\n| 22 | `faf pro` | Pro features \u0026 licensing |\n| 23 | `faf conductor` | Conductor integration |\n| 24 | `faf formats` | Show supported formats |\n| 25 | `faf info` | Version and system info |\n| 26 | `faf clear` | Clear cached data |\n\nRun `faf --help` for full options.\n\n---\n\n## Quick Start\n\n```bash\n# ANY GitHub repo — no clone, no install, 2 seconds\nbunx faf-cli git https://github.com/facebook/react\n\n# Your own project\nbunx faf-cli init              # Create .faf\nbunx faf-cli auto              # Zero to 100% in one command\nbunx faf-cli go                # Interactive interview to gold code\n```\n\n---\n\n## Scoring\n\n**🏆 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.\n\n| Tier | Score | Status |\n|------|-------|--------|\n| 🏆 **Trophy** | 100% | AI never has to guess |\n| ★ **Gold** | 99%+ | 1 slot from Trophy |\n| ◆ **Silver** | 95%+ | Close — keep going |\n| ◇ **Bronze** | 85%+ | Interim — keep going |\n| ● **Green** | 70%+ | Interim — keep going |\n| ● **Yellow** | 55%+ | AI flipping coins |\n| ○ **Red** | \u003c55% | AI working blind |\n| ♡ **White** | 0% | No context at all |\n\n---\n\n## Sync\n\n```\nbi-sync:   .faf  ←── 8ms ──→  CLAUDE.md                (free forever)\ntri-sync:  .faf  ←── 8ms ──→  CLAUDE.md ↔ MEMORY.md    (Pro)\n```\n\n---\n\n## Compiled Binaries\n\nBun's single-file compiler produces standalone binaries — no runtime needed.\n\n```bash\nbun run compile                # Current platform\nbun run compile:all            # darwin-arm64, darwin-x64, linux-x64, windows-x64\n```\n\nShip `faf` as a single binary for CI/CD, Docker, or air-gapped environments.\n\n---\n\n## Architecture\n\n```\nsrc/\n├── cli.ts              ← Entry point, 26 command registrations\n├── commands/           ← 26 command files (1 per command)\n├── core/               ← Types, slots (33 Mk4), tiers, scorer, schema\n├── detect/             ← Framework detection, stack scanner\n├── interop/            ← YAML I/O, CLAUDE.md, AGENTS.md, GEMINI.md\n├── ui/                 ← Colors (#00D4D4), display\n└── wasm/               ← faf-scoring-kernel wrapper (Rust → WASM)\n```\n\n**Toolchain:** Bun (test, build, compile) · TypeScript (strict) · WASM (scoring kernel)\n\n---\n\n## Testing\n\n\u003e **Robust. Reliable. Next-level WJTTC tested.** — The Foundation Edition.\n\n```bash\nbun test                       # 408 tests, 42 files, ~13s\n```\n\n- **WJTTC Build Resilience** (13) — every regression class locked.\n- **WJTTC Kernel Stress** (19) — WASM kernel boundary tests.\n- **e2e lifecycle** — every command in sequence.\n\nTest reports in `reports/`.\n\n---\n\n## Support\n\n- **[GitHub Discussions](https://github.com/Wolfe-Jam/faf-cli/discussions)** — Questions, ideas, community\n- **Email:** team@faf.one\n\n---\n\nIf `faf-cli` has been useful, consider starring the repo — it helps others find it.\n\n---\n\n## License\n\nMIT — Free and open source\n\n**IANA-registered:** [`application/vnd.faf+yaml`](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml)\n\n*format | driven 🏎️⚡️ [wolfejam.dev](https://wolfejam.dev)*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwolfe-jam%2Ffaf-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwolfe-jam%2Ffaf-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwolfe-jam%2Ffaf-cli/lists"}