"RAG performs retrieval at query time. FAR performs augmentation at file time." — FAR Paper, Kelly Peilin Chan, 2026

In Claude Code:

/plugin marketplace add mr-kelly/far
/plugin install far

Via npx (other AI agents):

npx skills add mr-kelly/far

Manual:

git clone https://github.com/mr-kelly/far.git

# Scan current directory (recursive)
far

# Scan specific directory
far ~/Documents/projects

# Process single file
far report.pdf

# Force regeneration (ignore cache)
far . --force

Add to AGENTS.md or system prompt — that's all:

When you encounter a binary file you cannot read
(.png, .pdf, .xlsx, .mp4), check for a .meta file
beside it. The .meta contains extracted content as
Markdown. For directory overviews, read .dir.meta.

cp skills/far/.env.example skills/far/.env
# Add OPENAI_API_KEY to enable OpenAI vision + transcription
# Optional (macOS):
# FAR_USE_APPLE_VISION=1
# FAR_USE_MACOS_METADATA=1
# FAR_APPLE_VISION_MAX_FRAMES=6

Without API keys, FAR falls back to local tools (Tesseract, FFprobe), and on macOS it also uses Apple Vision + Spotlight metadata on-device.

AI coding agents (Claude Code, Codex, GitHub Copilot) can read code — but they're blind to 30–40% of critical context stored in binary formats:

"An AI agent operating without access to these files is like a developer who can read code but is forbidden from looking at the design docs, the architecture diagrams, or the product requirements."

FAR generates a persistent .meta sidecar next to every binary file:

project/
├── budget.xlsx           ← Binary (opaque to AI)
├── budget.xlsx.meta      ← Markdown table (readable by AI)
├── architecture.png      ← Binary
├── architecture.png.meta ← Caption + OCR text
└── standup.mp4.meta      ← Full transcript + topics

No vector database. No embedding service. No runtime pipeline.

When running on macOS (default enabled):

• Apple Vision for images and video frames (OCR, labels, faces, barcodes/QR, body pose)
• Apple Vision feature-print fingerprint hash for image similarity workflows
• Spotlight (mdls) metadata enrichment in .meta files

Two-layer cache for instant incremental builds:

1. Fast check (mtime + size) — skip unchanged files in 0.003s
2. Content check (SHA-256) — detect true changes even if timestamp differs

Only files whose content has actually changed are re-extracted. The rest are instant cache hits.

.dir.meta is also content-stable: if directory summary content hasn't changed, FAR will not rewrite it (so extract.extracted_at won't churn on every scheduled run).

Auto-generated .dir.meta files let agents "browse" entire directories without reading every file:

project/.dir.meta       ← "What is this project?"
  src/.dir.meta         ← "What's in src/?"
  docs/.dir.meta        ← "What docs exist?"

• .farignore file (gitignore syntax) to exclude sensitive paths and directories
• Fully offline — no files leave your machine without API keys
• Selective extraction: mark directories as "metadata-only" (no content extraction)

RAG chunks documents into 500–1000 token fragments. This destroys structure:

Original table in report.pdf:
| Region  | Revenue | Growth |
| APAC    | $2.3M   | +28%   |   ← complete, meaningful
| NA      | $1.9M   | +12%   |

After RAG chunking:
  Chunk 37: "...APAC $2.3M +28% NA"
  Chunk 38: "$1.9M +12% Europe..."  ← table split, context lost

FAR preserves the full file structure in every .meta. The agent always gets the complete picture.

In 2005, Unity faced the same problem — game assets (.png, .fbx, .wav) are binary and opaque to the engine. Their solution: every asset gets a persistent text sidecar.

player.png      →   player.png.meta   (Unity: engine metadata)
report.pdf      →   report.pdf.meta   (FAR: AI-readable content)

Twenty years later, FAR applies the same insight to AI coding agents.

FAR sits at the file layer of the AI infrastructure stack — complementing, not replacing, existing tools:

---
far_version: 1
source:
  sha256: a1b2c3d4...
  mime: application/pdf
  size: 129509
extract:
  pipeline: far_gen_v14
  extracted_at: 2026-02-27T10:00:00Z
---
# report.pdf

## Executive Summary
Revenue grew 23% YoY driven by APAC expansion.

## Table 1 - Revenue by Region
| Region       | Q3 2025 | Growth |
|--------------|---------|--------|
| Asia-Pacific | $2.3M   | +28%   |
| N. America   | $1.9M   | +12%   |

File-Augmented Retrieval: Making Every File Readable to Coding Agents via Persistent .meta Sidecars

Kelly Peilin Chan, 2026

Full documentation in skills/far/SKILL.md

MIT License