faf-cli

The command-line tool for the Foundational AI-context Format (.faf).

Get Started View on GitHub
# one-off, no install
bunx faf-cli init
bunx faf-cli auto
bunx faf-cli export --agents

What is faf-cli?

faf-cli reads a real project and writes a structured project.faf file — the single source of truth for AI coding agents.

From that file it can generate the instruction files agents actually read (AGENTS.md, CLAUDE.md, .cursorrules, GEMINI.md).

It is also the authoring engine for the FAF MCP servers.

What is .faf?

.faf is an open, IANA-registered format (application/vnd.faf+yaml) for persistent project context.

It holds the facts an agent needs — language, stack, commands, structure, and constraints — in a versioned file that travels with the code.

A minimal example

# project.faf (excerpt)
project:
  name: my-api
  language: typescript
  runtime: node
commands:
  test: npm test
  build: npm run build
  lint: npm run lint
stack:
  - express
  - postgres
constraints:
  - never commit .env

This is the single source. Agent instruction files are generated from it.

The human context

Most of what's in project.faf is mechanical — language, stack, commands. AGENTS.md and its siblings cover that ground well.

The facts an agent usually can't infer are intent: who a project is for, why it exists, when it's likely to change. .faf has a dedicated slot for exactly that — six questions, one answer each.

The same project, with intent

# project.faf (excerpt, continued)
human_context:
  who: backend developers on the payments team
  what: the internal API that issues and refunds payments
  why: replace three undocumented internal scripts
  where: runs on the Kubernetes cluster, staging and prod
  when: active development, weekly releases
  how: request → validate → charge provider → record ledger entry

AGENTS.md makes a start on context. The six-W slots finish the job — instructions plus intent, in one file.

Why it exists

Human READMEs and hand-written agent instruction files drift. Agents then re-discover the same project facts on every session.

faf-cli creates and maintains the structured context file so the facts stay accurate and the agent files can be regenerated from them.

Who it is for

  • Developers who use AI coding agents (Claude Code, Cursor, Codex, Gemini, and others)
  • Teams that want consistent context across multiple agents
  • Anyone maintaining MCP servers that need reliable project context

How to use it

One-off (no install)

bunx faf-cli init
bunx faf-cli auto
bunx faf-cli export --agents

Produces a versioned project.faf and regenerates the agent instruction files (AGENTS.md, CLAUDE.md, .cursorrules, GEMINI.md) from it.

Installed (regular terminal use)

npm install -g faf-cli
# or
bun add -g faf-cli
# or
brew install wolfe-jam/faf/faf-cli

Then run faf in any project.

MCP

faf-cli is the authoring and maintenance engine for the FAF MCP servers.

The same project.faf file that the CLI produces is what the MCP tools read and expose to agents.

FAQ

Does it replace AGENTS.md?
No — it enhances it. .faf fills the gaps AGENTS.md leaves open: structured facts, versioning, and the human-context (who/what/why/where/when/how) fields most instruction files never capture.
Does it work with CLAUDE.md, GEMINI.md, and others?
Yes — faf-cli export --agents generates AGENTS.md, CLAUDE.md, .cursorrules, and GEMINI.md from the same project.faf source, so every agent reads the same facts.
Do I have to write the YAML by hand?
No — faf-cli auto scans the project and drafts it. Anything it can't verify from the code is left blank rather than guessed.
What happens to my existing AGENTS.md?
faf-cli writes it as a managed block. Anything outside the <!-- faf:start --> / <!-- faf:end --> markers is left untouched.