flatten-tool

A CLI utility to flatten directory structures, with perfect GitHub Flavored Markdown compatibility including explicit HTML anchors for maximum portability.

Watch the YouTube video for an example of why you might need to flatten project files into a single document for AI discussions and code reviews.

Installation

Requires Bun runtime (v1.1+).

Via npm

npm install -g flatten-tool

Run without installation

You can run flatten-tool directly without installing:

npx flatten-tool [args]
bunx flatten-tool [args]

For Development

With devenv (recommended)

Clone the repository and enter the development environment:

git clone https://github.com/MBanucu/flatten-tool.git
cd flatten-tool
devenv shell

Inside the devenv shell, dependencies are managed automatically. Run the tool with:

bun run index.ts [args]

Without devenv

Clone the repository and install dependencies:

git clone https://github.com/MBanucu/flatten-tool.git
cd flatten-tool
bun install

Run directly with Bun:

bun run index.ts [args]

Usage

By default, the tool merges all file contents into a single Markdown file, starting with a project file tree for navigation, followed by each file's content under a header with its full relative path, in a code block with appropriate language highlighting based on the file extension. The tree includes clickable links to file sections using GitHub-compatible anchors. Ignores and filters are applied as usual.

The <source> argument is optional and defaults to the current directory (.). The <target> argument is also optional and defaults to flattened.md (or flattened/ when using --directory).

Options

• --clipboard, -c: Copy the generated Markdown content to clipboard (only for Markdown mode).
• --directory, -d: Flatten to individual files in a directory instead of merging to Markdown.
• --dry-run, -n: Preview changes without modifying the filesystem.
• --move, -m: Move files instead of copying (original files will be deleted).
• --overwrite, -o: Overwrite existing target files.
• --gitignore, -g: Respect .gitignore files (default: true). Use --no-gitignore to disable.
• --help, -h: Show help.
• --version, -v: Show version.

Examples

Flatten current directory to flattened.md:

flatten-tool

Flatten a specific directory to flattened.md:

flatten-tool /path/to/source

Flatten current directory to a custom Markdown file:

flatten-tool output.md

Flatten a specific directory to a custom Markdown file:

flatten-tool /path/to/source output.md

Flatten to individual files in a directory:

flatten-tool --directory

This creates a flattened/ directory with flattened files.

Flatten a specific directory to a custom output directory:

flatten-tool /path/to/source output-dir --directory

Move files instead of copying:

flatten-tool --move

Overwrite existing files:

flatten-tool --overwrite

Combine options:

flatten-tool /path/to/source output.md --move --overwrite

Flatten current directory to Markdown and copy to clipboard:

flatten-tool --clipboard

Preview flattening without changes:

flatten-tool --dry-run

Testing

Run all tests:

unittest  # If using devenv
bun unittest  # Otherwise

Run tests in watch mode:

bun test --watch

Run a specific test:

bun test -t "flattens a simple nested directory"

Development

This project uses Bun for runtime, TypeScript for type safety, and follows the guidelines in AGENTS.md for coding standards.

Development Scripts (devenv)

When using devenv, the following scripts are available:

• check: Format + lint in one go
• format: Format code with Biome
• lint: Run Biome lint
• unittest: Run all tests with Bun

Changelog

See CHANGELOG.md for a full list of changes.

License

This project was created using bun init in bun v1.3.8. Bun is a fast all-in-one JavaScript runtime.