Monopack

monopack is a CLI tool that packs an entire directory structure into a single Markdown file — and can unpack it back into its original files. It is designed for developers who want to easily archive, share, and version entire codebases as readable and LLM-friendly Markdown documents.

Features

• 📦 Pack directories into Markdown

  • Recursively scans source files based on include/exclude patterns.
  • Preserves directory hierarchy in a tree view.
  • Embeds file contents in fenced code blocks with language tags.

• 📂 Unpack Markdown back into files

  • Fully restores the directory and file structure from the Markdown archive.
  • Detects and safely handles overwriting with the --force option.

• ⚙️ Flexible include/exclude configuration

  • Include/exclude patterns can be defined via command line options or configuration files.

• 🔒 Encryption/decryption options (not yet implemented)

  • CLI flags for --encrypt / --decrypt are defined but not yet implemented.

Installation

You can build and install monopack using Cargo:

cd <monopack>
cargo install --path .

Usage

Pack a directory

monopack pack ./src -o project.md --include "**/*.rs,**/*.py" --exclude "target/*"

This command:

• Recursively scans src/
• Includes only .rs and .py files
• Excludes the target/ directory
• Writes the result to project.md

Unpack a Markdown archive

monopack unpack project.md -o ./restored

This restores all files from the Markdown archive into ./restored.

Configuration

CLI-based filters

You can specify include/exclude patterns directly:

--include "**/*.rs,**/*.py" --exclude "target/*"

Config files

monopack can also read configuration files from the current directory or a specified path:

• .monopack_include — patterns of files to include
• .monopack_ignore — patterns of files to exclude

Config file example:

Each file should contain one glob pattern per line. Blank lines and lines starting with # are ignored.

.monopack_include:

**/*.rs
**/*.py

This example tells monopack to include all Rust (.rs) and Python (.py) files recursively.

.monopack_ignore:

target/*
**/__pycache__/*
.git/*

This example excludes the build directory, Python cache folders, and the .git directory.

Config file search priority:

1. --config-dir CLI option
2. MONOPACK_CONFIG_DIR environment variable
3. Current working directory (.)

Pattern priority (CLI vs config files)

The include/exclude patterns can be specified in two ways:

1. CLI options — --include, --exclude
2. Config files — .monopack_include, .monopack_ignore

If both are present, CLI options always take precedence. When CLI patterns are given, monopack completely ignores the config files.

Source	Priority	Description
--include, --exclude	High	Explicit patterns passed from the command line
.monopack_include, .monopack_ignore	Medium	Loaded automatically from the config directory
(Default)	Low	Includes all files (**/*) if no patterns are specified

Additional notes

You can specify a custom directory for config files using --config-dir or the environment variable MONOPACK_CONFIG_DIR.

You may provide only one of the config files — for example, use .monopack_include alone if you only need inclusion rules, or .monopack_ignore alone if you only need exclusions. monopack will automatically fall back to defaults for the missing file.

If neither CLI options nor config files are provided, monopack includes all files recursively by default (**/*).

Syntax highlighting

monopack automatically detects file extensions and applies language-specific fenced code blocks for syntax highlighting.

Common languages such as Rust, Python, C/C++, Markdown, JavaScript, TypeScript, Go, Java, and Shell scripts are supported out of the box.

Files with unsupported extensions are written as fenced code blocks without a language tag.

CLI Options

Pack Command

monopack pack <SRC_DIR> -o <OUTPUT> [OPTIONS]

Option	Description
--include	Comma-separated glob patterns to include (default: **/*)
--exclude	Comma-separated glob patterns to exclude (default: None)
--config-dir	Directory to search for .monopack_include / .monopack_ignore
--force	Overwrite existing output file or create missing directories
--encrypt / --passphrase	(Not implemented yet)

Unpack Command

monopack unpack <INPUT> -o <OUTPUT> [OPTIONS]

Option	Description
--force	Overwrite existing files
--decrypt / --passphrase	(Not implemented yet)

LICENSE

This project is distributed under the MIT License.