flatt

flatt

flatt turns a local code folder into a clean text digest for LLMs, AI agents, and quick inspection.

It can run in manual mode with include/exclude patterns, or in smart mode where an OpenAI-compatible LLM helps decide which files should be kept before generating flatt.txt.

Install

Install script (macOS / Linux)

Downloads the latest prebuilt binary from GitHub Releases and installs it to a directory on your PATH:

curl -fsSL https://raw.githubusercontent.com/ArmanJR/flatt/main/install.sh | sh

Pin a specific version or install directory:

curl -fsSL https://raw.githubusercontent.com/ArmanJR/flatt/main/install.sh | sh -s -- v1.0.0
VERSION=v1.0.0 BINDIR="$HOME/.local/bin" sh -c "$(curl -fsSL https://raw.githubusercontent.com/ArmanJR/flatt/main/install.sh)"

Prebuilt binaries

Download an archive for your OS/arch from the releases page (Windows users: use the .zip), verify it against checksums.txt, extract flatt, and place it on your PATH.

Go

go install github.com/armanjr/flatt/cmd/flatt@latest

From source

go build ./cmd/flatt

Usage

flatt ./project
flatt ./project --smart
flatt ./project --include "*.go,*.md"
flatt ./project --exclude "node_modules/*,.venv/"
flatt --settings
flatt --version

flatt.txt is always written to the current working directory. If it already exists, flatt overwrites it and shows a warning.

Modes

Manual mode

Manual mode runs when --include or --exclude is provided. It does not open the TUI.

flatt ./project --include "*.go,README.md"
flatt ./project --exclude "node_modules/*,.venv/"

Behavior:

• --include keeps only matching safe text files and overrides .gitignore.
• --exclude removes matching files and also respects .gitignore files in the project tree.
• --include and --exclude can be combined; include is applied first, then exclude.
• Binary/media files and secret-like files are always skipped.

Smart mode

Smart mode is the default when neither --include nor --exclude is present.

flatt ./project

Smart mode:

• reads README.md or readme.md
• asks for a project description if no README exists
• scans one directory depth at a time
• asks the configured LLM which current-depth files and folders to keep
• shows keep/drop decisions before applying them
• lets you toggle decisions, retry the LLM, or manually keep/drop all current items
• writes the final digest to ./flatt.txt

Settings

Run:

flatt --settings

Settings are saved under the operating system's user config directory:

<user-config-dir>/flatt/.env

Common examples are ~/.config/flatt/.env on Linux and ~/Library/Application Support/flatt/.env on macOS. TUI diagnostics are written to flatt.log in the same directory.

Supported AI providers:

• OpenAI: https://api.openai.com/v1
• OpenRouter: https://openrouter.ai/api/v1
• Ollama: http://localhost:11434/v1

OpenAI requires OPENAI_API_KEY, OpenRouter requires OPENROUTER_API_KEY, and Ollama requires no API key.

Output

The generated digest contains:

Directory structure:
...

File contents:
================================================
FILE: src/main.go
================================================
...

Safety

flatt skips common binary/media files, .git/, symlinked files and directories, flatt.txt, OS junk files, and secret-like files such as .env, private keys, certificates, and kubeconfig files.

Text SVG files are treated as text and can be included unless excluded by pattern or .gitignore.

Smart mode sends path metadata and project description to the LLM. It does not send file contents to the LLM.

Releasing

Releases are automated with GoReleaser and GitHub Actions. Pushing a semver tag builds cross-platform binaries (linux, macOS, windows for amd64/arm64), generates checksums.txt, and publishes a GitHub Release.

git tag v1.0.0
git push origin v1.0.0

The version reported by flatt --version is injected from the tag at release build time, and go install ...@vX.Y.Z reports the same version via Go's build metadata.