📨 A command-line tool for exchanging collections of files with Large Language Models - bundle multiple files into a single clipboard-ready document while preserving directory structure and metadata... good for code reviews, project sharing, and LLM interactions.
- 🔄 Interactive Reviews: Review and apply LLM-proposed changes one by one.
- 📋 Clipboard Integration: Seamless copying and pasting by default.
- 🗂️ Directory Structure: Preserves hierarchical file organization.
- 🛡️ Path Protection: Safeguards against dangerous modifications.
Download the latest standalone executable for your platform from GitHub Releases. These executables have no dependencies and work out of the box.
Install via uv
tool command:
uv tool install mimeogram
Or, install via pipx:
pipx install mimeogram
Install via uv pip
command:
uv pip install mimeogram
Or, install via pip:
pip install mimeogram
Below are some simple examples. Please see the examples documentation for more detailed usage patterns.
usage: mimeogram [-h] [OPTIONS] {create,apply,provide-prompt,version}
Mimeogram: hierarchical data exchange between humans and LLMs.
╭─ options ────────────────────────────────────────────────────────────────────╮
│ -h, --help show this help message and exit │
│ --configfile {None}|STR │
│ (default: None) │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ subcommands ────────────────────────────────────────────────────────────────╮
│ {create,apply,provide-prompt,version} │
│ create Creates mimeogram from filesystem locations or URLs. │
│ apply Applies mimeogram to filesystem locations. │
│ provide-prompt Provides LLM prompt text for mimeogram format. │
│ version Prints version information. │
╰──────────────────────────────────────────────────────────────────────────────╯
Use with API workbenches and with LLM GUIs which do not support persistent user-customized instructions (e.g., DeepSeek, Google Gemini, Grok):
Bundle files with mimeogram format instructions into clipboard.
mimeogram create src/*.py tests/*.py --prepend-prompt
Paste instructions and mimeogram into prompt text area in browser.
Interact with LLM until you are ready to apply results.
Request mimeogram from LLM and copy it from browser to clipboard.
- Example: Claude Artifact
- (may need to remix to see it because of Claude.ai display bug)
Apply mimeogram parts from clipboard. (On a terminal, this will be interactive by default.)
mimeogram apply
Note that, if you do not want the LLM to return mimeograms to you, most of the current generation of LLMs are smart enough to understand the format without instructions. Thus, you can save tokens by not explicitly providing mimeogram instructions.
Some LLM service providers have the concept of projects. These allow you to organize chats and persist a set of instructions across chats. Projects might only be available for certain models. Examples of LLM service providers, which support projects with some of their models, are Claude and ChatGPT.
In these cases, you can take advantage of the project instructions so that you do not need to include mimeogram instructions with each new chat:
Copy mimeogram format instructions into clipboard.
mimeogram provide-prompt
Paste mimeogram prompt into project instructions and save the update. Any new chats will be able to reuse the project instructions hereafter.
Simply create mimeograms for new chats without prepending instructions.
mimeogram create src/*.py tests/*.py
Same workflow as chats without project support at this point: interact with LLM, request mimeogram (as necessary), apply mimeogram (as necessary).
You can also create mimeograms from remote URLs:
mimeogram create https://raw.githubusercontent.com/BurntSushi/aho-corasick/refs/heads/master/src/dfa.rsBoth local and remote files may be bundled together in the same mimeogram.
However, there is no ability to apply a mimeogram to remote URLs.
During application of a mimeogram, you will be, by default, presented with the chance to review each part to apply. For each part, you will see a menu like this:
src/example.py [2.5K]
Action? (a)pply, (d)iff, (e)dit, (i)gnore, (s)elect hunks, (v)iew >
Choosing a to select the apply action will cause the part to be queued
for application once the reivew of all parts is complete. All queued parts are
applied simultaneously to prevent thrash in IDEs and language servers as
interdependent files are reevaluated.
If an LLM proposes the alteration of a sensitive file, such as one which may contain credentials or affect the operating system, then the program makes an attempt to flag this:
~/.config/sensitive.conf [1.2K] [PROTECTED]
Action? (d)iff, (i)gnore, (p)ermit changes, (v)iew >
If, upon review of the proposed changes, you believe that they are safe, then
you can choose p to permit them, followed by a to apply them.
We take AI safety seriously. Please review all LLM-generated content, whether it is flagged for a sensitive destination or not.
Mimeogram creates a configuration file on first run. You can find it at:
- Linux:
~/.config/mimeogram/general.toml - macOS:
~/Library/Application Support/mimeogram/general.toml - Windows:
%LOCALAPPDATA%\\mimeogram\\general.toml
[apply]
from-clipboard = true # Read from clipboard by default
[create]
to-clipboard = true # Copy to clipboard by default
[prompt]
to-clipboard = true # Copy prompts to clipboard
[acquire-parts]
fail-on-invalid = false # Skip invalid files
recurse-directories = false
[update-parts]
disable-protections = false- Cost optimization through GUI-based LLM services vs API billing.
- Support for batch operations instead of file-by-file interactions.
- Preserves hierarchical directory structure.
- Version control friendly. (I.e., honors Git ignore files.)
- Supports async/batch workflows.
- IDE and platform agnostic.
- No premium subscriptions required.
- Works with LLM GUIs lacking project functionality.
- Manual refresh of files needed (no automatic sync).
- Cannot retract stale content from conversation history in provider GUIs.
- Consider dedicated tools (e.g., Cursor) for tighter collaboration loops.
| Feature | Mimeograms | Projects (Web) [1] | Agents and Tools [3] | Specialized IDEs [2] |
|---|---|---|---|---|
| Cost Model | Flat rate | Flat rate | Usage-based | Flat rate |
| Directory Structure | Yes | No | Yes [4] | Yes |
| IDE Integration | Any | Web-only | Varies | One |
| Setup Required | Download | None | Varies | Varies |
| Version Control | Yes | No | Yes [4] | Yes |
| Platform Support | Universal | Web | Varies | Varies |
| Automation Support | Yes | No | Varies | Varies |
| [1] | ChatGPT and Claude.ai subscription feature |
| [2] | Cursor, Windsurf, etc... |
| [3] | Aider, Claude Code, etc... |
| [4] | (1, 2) Requires custom implementation |
Notes:
- "Agents and Tools" refers to custom applications providing I/O tools for LLMs to use via APIs, such as the Anthropic or OpenAI API.
- Cost differences can be significant at scale, especially when considering cache misses against APIs.
Mimeogram is unique among file collection tools for LLMs in offering round-trip support - the ability to not just collect files but also apply changes proposed by LLMs.
| Feature | Mimeogram | Gitingest | Repomix | dump_dir |
|---|---|---|---|---|
| Round Trips | ✓ | |||
| Clipboard Support | ✓ | ✓ | ✓ | |
| Remote URL Support | ✓ | ✓ | ✓ | |
| Security Checks | ✓ | ✓ |
Tools in this space generally follow one of two approaches: filesystem-oriented or repository-oriented.
Tools, like mimeogram, dump_dir, and ai-digest, are oriented around
files and directories. You start with nothing and select what is needed. This
approach offers more precise control over context window usage and is better
suited for targeted analysis or specific features.
Tools, like gitingest and repomix, are oriented around code
repositories. You start with an entire repository and then filter out unneeded
files and directories. This approach is better for full project comprehension
but requires careful configuration to avoid exceeding LLM context window
limits.
Contribution welcome. Please see the contribution guide for:
- Code of Conduct
- Development Setup
- Coding Guidelines
The name "mimeogram" draws from multiple sources:
- 📜 From Ancient Greek roots:
- μῖμος (mîmos, "mimic") + -γραμμα (-gramma, "written character, that which is drawn")
- Like mimeograph but emphasizing textual rather than pictorial content.
- 📨 From MIME (Multipurpose Internet Mail Extensions):
- Follows naming patterns from the Golden Age of Branding: Ford Cruise-o-matic, Ronco Veg-O-Matic, etc....
- Reflects the MIME-inspired bundle format.
- 📬 Echoes telegram:
- Emphasizes message transmission.
- Suggests structured communication.
Note: Despite similar etymology, this project is distinct from the PyPI package mimeograph, which serves different purposes.
Pronunciation? The one similar to mimeograph seems to roll off the tongue more smoothly, though it is one more syllable than "mime-o-gram". Preferred IPA: /ˈmɪm.i.ˌoʊ.ɡræm/.
