flatcat 🐱

Flatten a codebase into a single Markdown file for easy sharing and LLM pair programming.

Flatcat recursively walks through your project directory and creates a clean, organized Markdown file containing:

• 📁 A visual directory tree (with ignored directories marked)
• 📄 Full contents of all text files with syntax highlighting
• 🎯 Smart filtering to exclude build artifacts, dependencies, and clutter

Perfect for sharing codebases with LLMs, code reviews, documentation, or getting a complete overview of a project.

✨ Features

• LLM-optimized: Produces clean, token-efficient output ideal for ChatGPT, Claude, etc.
• Smart filtering: Automatically ignores .git/, node_modules/, __pycache__/, and other common directories
• Gitignore integration: Respects your .gitignore files
• Syntax highlighting: Uses appropriate code fences for each file type
• Highly configurable: Customize filtering, formatting, and output via TOML config
• Auto-incrementing output: Never overwrites existing files

🚀 Installation

# Install with pipx (recommended)
pipx install flatcat

# Or with pip
pip install flatcat

📖 Quick Start

# Flatten current directory
flatcat

# Flatten a specific directory
flatcat /path/to/your/project

# Flatten with custom output name
flatcat --out my-project-snapshot.md /path/to/project

# Generate a config file to customize behavior
flatcat init

📋 Example Output

# Flattened view of `/home/user/my-project`

## Directory tree

/home/user/my-project ├── .git * ├── node_modules * ├── src │ ├── components │ │ ├── Header.jsx │ │ └── Footer.jsx │ ├── utils │ │ └── helpers.js │ └── App.js ├── package.json └── README.md

_* = ignored directory (contents not listed)_

### src/App.js
```js
import React from 'react';
// ... full file contents

package.json

{
  "name": "my-project",
  // ... full file contents
}

## ⚙️ Configuration

Create a `flatcat.toml` file to customize behavior:

```bash
flatcat init  # Creates flatcat.toml with defaults

Example Configuration

# Basic settings
root = "."
output = "flatcat.md"
include_tree = true
tree_depth = 0  # 0 = unlimited depth
respect_gitignore = true

# File types to ignore
ignore_extensions = [".png", ".jpg", ".gif", ".exe", ".zip", ".pdf"]

[filters]
# Only include files matching these patterns (empty = include all)
include = []

# Exclude files/directories matching these patterns
exclude = [
    "**/__pycache__/**", "__pycache__",
    "venv/**", "venv", ".venv/**", ".venv",
    ".git/**", ".git",
    "node_modules/**", "node_modules",
    "build/**", "dist/**",
    "*.egg-info/**", "*.egg-info"
]

[format]
# Customize how files are presented
heading = "### {path}"
fence_language_from_extension = true
preamble = """
This file was generated by flatcat.

It contains a tree view of {root} and the full text of non-ignored files.
Directories marked with * are ignored; their contents are not listed.
"""

🤖 Perfect for LLM Pair Programming

Flatcat was designed specifically for sharing codebases with AI assistants:

# Generate a clean snapshot of your project
flatcat my-web-app

# Share the resulting markdown file with ChatGPT, Claude, etc.
# The AI gets full context of your project structure and code!

Why LLMs love flatcat output:

• 🎯 Focused: No build artifacts or dependencies cluttering the context
• 📊 Structured: Clear tree view shows project organization
• 🔍 Complete: All source code in one place with proper syntax highlighting
• 💰 Token-efficient: Smart filtering reduces token usage costs

📚 Command Line Options

Usage: flatcat [directory] [options]

Arguments:
  directory              Directory to flatten (default: current directory)

Options:
  -c, --config PATH      Path to TOML config file (default: flatcat.toml)
  --out PATH             Output file path (default: <dirname>-flatcat.md)
  --no-tree              Disable directory tree in output
  -h, --help             Show help message

Subcommands:
  init [path]            Generate a starter flatcat.toml config file

🛠️ Use Cases

• LLM Pair Programming: Share your entire codebase context efficiently
• Code Reviews: Generate comprehensive snapshots for review
• Documentation: Create living documentation of project structure
• Onboarding: Help new team members understand project layout
• Archiving: Preserve project snapshots in readable format
• Analysis: Get a bird's-eye view of large codebases

🔧 Development

# Clone the repository
git clone https://github.com/yourusername/flatcat.git
cd flatcat

# Install in development mode
pip install -e .

# Run tests
python -m pytest

# Install development dependencies
pip install -e ".[dev]"

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

📄 License

This project is licensed under the MIT License

🙏 Acknowledgments

• Inspired by the need for better LLM-codebase interaction
• Built with modern Python tooling and best practices

---