🥞 fln

Your entire codebase → One AI-ready file.

Stop wrestling with file pickers and attachment limits — feed your whole project to any LLM in one shot.

fln .

Or run instantly:

npx fln . -o codebase.md

Works with Claude, ChatGPT, Gemini, Grok, Cursor, Copilot, and any AI tool.

fln (short for flatten) is language-agnostic by design: TypeScript, Python, Java, Go, Rust, Bash, SQL, mixed monorepos — it treats everything as plain text, detects project metadata from common manifests (package.json, pyproject.toml, pom.xml, go.mod, Cargo.toml, CMakeLists.txt, vcpkg.json), respects .gitignore, and skips binaries by default.

Why fln exists

If you use LLMs for real projects, you’ve hit these limits:

• Context windows — large projects don’t fit.
• Upload friction — selecting dozens of files for every session.
• Partial understanding — AI sees fragments, not the architecture.
• Manual prep — repeating the same setup context again and again.

fln removes that overhead.
It turns your project into a single, structured snapshot that LLMs can actually reason about.

What fln enables

→ Full-context refactoring
Ask architectural questions that are impossible file-by-file:

“Where is the real coupling here?”
“What should be split into modules?”

→ Instant onboarding
One markdown file instead of “start by opening these 12 folders”. Perfect for reading code on a tablet or onboarding new developers without an IDE.

→ Project-level code reviews
Let AI detect patterns, inconsistencies, and risks across the entire codebase.

→ Auditable Snapshots
Create a single, clean artifact of your codebase state for security reviews, compliance audits, or legal records without granting full repo access.

→ Dataset Preparation
Generate clean, formatted data for RAG pipelines and fine-tuning custom models.

→ LLM-friendly diffs
Flatten → commit → flatten again. See how the whole project changed structurally.

Compatible with your AI workflow

• Claude — ideal for large architectural prompts (200K+ tokens).
• Gemini — push massive codebases into 1M token windows.
• ChatGPT — single-shot analysis without attachments.
• Cursor / Windsurf — reference the full project in prompts.
• GitHub Copilot — better context → better suggestions.
• Local LLMs — datasets for RAG and fine-tuning.

Built for real projects

• ⚡ Fast parallel scanning — thousands of files in seconds.
• 🎯 Smart filtering — respects .gitignore, excludes binaries, configurable size limits.
• 📁 Intentional file order — entry points and configs first, not alphabetical noise.
• 🔄 Auto-detection — skips files previously generated by fln.
• 📐 Deterministic output — same input → same snapshot.
• 🧠 Project metadata detection — name & version from ecosystem-native manifests.
• 🛠️ Developer-friendly — Markdown for humans, JSON for tooling, --dry-run mode for safety.
• 🔒 No surprises — runs locally, no data leaves your machine.

Zero dependencies on external services. Zero tracking. Just a tool that does its job.

Install

npm

npm install -g fln

Linux & macOS (view install script)

curl -fsSL https://fln.nesvet.dev/install | sh

Windows (view install script)

powershell -c "irm fln.nesvet.dev/install.ps1 | iex"

Or just run without installing

npx fln . -o codebase.md

One-line installer options (macOS/Linux)

Pin a version or custom install directory:

curl -fsSL "https://fln.nesvet.dev/install" | FLN_VERSION="<version>" INSTALL_DIR="$HOME/.local/bin" sh

One-line installer options (Windows PowerShell)

$env:FLN_VERSION = "<version>"
$env:INSTALL_DIR = "$env:LOCALAPPDATA\\fln\\bin"
powershell -c "irm fln.nesvet.dev/install.ps1 | iex"

Manual download (GitHub Releases)

curl -L "https://github.com/nesvet/fln/releases/latest/download/fln-macos-x64.tar.gz" | tar -xz -C /usr/local/bin
chmod +x /usr/local/bin/fln

Usage

fln [directory] [options]

Examples:

# Flatten entire project
fln .

# Exclude tests and fixtures
fln src -e "**/*.test.ts" -e "fixtures/"

# Force include a file (even if ignored)
fln . -i "dist/output.md"

# Generate JSON for tooling
fln . --no-contents --format json

# Preview without writing
fln . --dry-run

# Overwrite output file instead of creating codebase-1.md
fln . -o codebase.md -w

• -o, --output <path> Output file or directory
• -w, --overwrite Overwrite output file instead of adding numeric suffix
• -e, --exclude <glob> Exclude patterns (repeatable)
• -i, --include <glob> Force include patterns
• --include-hidden Include hidden files and directories
• --no-gitignore Ignore .gitignore
• --max-size <size> Max file size (10mb, 512kb)
• --max-total-size <size> Max total included size
• --no-contents Exclude file contents
• --no-tree Exclude directory tree
• --format <md|json> Output format
• --dry-run Scan without writing output
• --follow-symlinks Follow symlinks
• --no-ansi Disable ANSI colors
• --no-sponsor-message Hide support message (also: FLN_NO_SPONSOR=1)
• --generated-date <date> Use this date in the “Generated” header (format: YYYY-MM-DD HH:mm)
• --banner <text> Add text at the beginning
• --footer <text> Add text at the end of the output
• -q, --quiet Minimal output
• -V, --verbose Verbose output with breakdown
• --debug Debug output with file list
• -v, --version Show version
• -h, --help Show help

CI/CD & Automation

Integrate fln into your pipeline to keep your codebase “AI-ready” automatically.

GitHub Actions: Auto-generate Snapshots

Generate a fresh codebase.md artifact on every push. Download it anytime to chat with LLMs about the exact state of your main branch or a specific PR without manual scanning.

Create .github/workflows/codebase-snapshot.yaml:

name: Snapshot Codebase

on:
  push:
    branches: [ "main" ]
  pull_request:

jobs:
  snapshot:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v6

      - name: Generate Snapshot
        # Generates codebase.md without installing fln globally
        run: npx fln . -o codebase.md -w --no-ansi

      - name: Upload Artifact
        uses: actions/upload-artifact@v6
        with:
          name: codebase-snapshot
          path: codebase.md
          retention-days: 7

Git Hooks: Pre-commit Context Guard

Prevent accidental “context bloat” (e.g., committing large datasets or wrong lockfiles) by failing commits if the flattened codebase exceeds a specific size. This ensures your project always fits within LLM context windows.

Add to your pre-commit hook (e.g., via husky or lint-staged):

# Fails the commit if the flattened codebase exceeds 5MB (configurable)
# --dry-run ensures no files are written to disk
npx fln . --dry-run --max-total-size 5mb

JavaScript API

import { fln } from "fln";

const result = await fln({
  rootDirectory: "./src",
  outputFile: "output.md",
  overwrite: true,
  excludePatterns: [ "*.test.ts", "fixtures/" ],
  format: "md",
  onProgress: (current, total) => {
    console.log(`Progress: ${current}/${total}`);
  }
});

console.log(`Processed ${result.files} files`);
console.log(`Output: ${result.outputPath}`);
console.log(`Tokens: ${result.outputTokenCount}`);

All CLI options are available via FlnOptions.

Advanced

{
	"outputFile": "output.md",
	"overwrite": false,
	"excludePatterns": [
		"dist/",
		"**/*.snap"
	],
	"includePatterns": [],
	"includeHidden": false,
	"useGitignore": true,
	"maximumFileSizeBytes": "10mb",
	"maximumTotalSizeBytes": "0",
	"includeTree": true,
	"includeContents": true,
	"format": "md",
	"followSymlinks": false,
	"logLevel": "normal",
	"generatedDate": "2026-02-09 12:00",
	"banner": "This is a snapshot of the codebase.",
	"footer": "End of snapshot."
}

• Uses project name + version if available (package.json, pyproject.toml, pom.xml, go.mod, Cargo.toml, CMakeLists.txt or vcpkg.json)
• md includes tree + contents
• json includes rootDirectory, tree, stats

Node.js

• Requires Node.js >=18.3
• ESM-only package ("type": "module")
• CLI works via npm i -g fln or npx fln

Bun

• Requires Bun >=1.0.0
• CLI works via bun install -g fln or bunx fln

Preview

Full real outputs are provided below. Each example is a compact project in examples/. fln outputs the directory tree and file contents with entry points and configs first (intentional file order):

• TypeScript
• Python
• Java
• Go
• Rust

Support this project

fln is free, open-source, and maintained by one developer.

If it saves you time or improves your AI workflow:

• ⭐️ Star the repo — it genuinely helps discoverability
• 💙 Support on Patreon — priority features & long-term maintenance

Contributing

PRs and issues are welcome.
See CONTRIBUTING.md for setup and guidelines.

License

MIT