flatten-mcp: Lossless Session Compression for Claude Code

Overview

flatten-mcp is a tool designed to reduce the token count and file size of Claude Code sessions. It achieves this by moving bulky tool results, such as large file contents, logs, and screenshots, into a local backup file. Unlike previous methods that rewrite history into summaries or delete content, flatten-mcp performs a lossless, reversible operation. It keeps the original data intact in a backup while replacing it in the active session with lightweight markers. This allows the session to resume with significantly fewer tokens.

Benefits

• Significant Token Savings: In read-heavy sessions involving large files and logs, users have observed reductions from 340,071 tokens down to 132,800 tokens. This represents a 61% reduction. Savings are most dramatic when sessions approach or exceed 200k tokens.
• Lossless Restoration: The process is reversible. Using the unflatten command restores the session to its original byte-for-byte state, deleting the backup file in the process.
• Zero Token Cost: The flattening process is a file operation, not a model inference task. It costs no tokens and is instant.
• Crash-Safe: The tool writes backups before modifying the active session file using atomic operations, ensuring data integrity even if the process is interrupted.

Use Cases

flatten-mcp is primarily used within the Claude Code environment to manage large sessions. It is ideal for developers who work with extensive logs, large code files, or numerous screenshots during a single session. The tool helps keep the active context light, allowing the AI to focus on the current task without being overwhelmed by historical data. Users can run a dry run to preview potential savings before making changes. They can also retrieve specific flattened blocks, such as a screenshot, to a file if needed. The tool supports macOS, Linux, and WSL2, making it accessible for most developers.

Pricing

flatten-mcp is available as an open-source tool on GitHub. It can be installed via npm or as a Claude Code plugin. There are no subscription fees or hidden costs associated with using the tool itself. The hosted endpoint is also available for use with Claude.ai, Cursor, or VS Code without local installation.

Vibes

The tool has received positive feedback for its efficiency and safety. Users appreciate the ability to save significant tokens without losing any data. The crash-safe feature ensures that sessions are not corrupted if the process is interrupted. The open-source nature of the tool allows users to verify its security and functionality. The small codebase and lack of telemetry or analytics further enhance trust among users.

Additional Information

flatten-mcp was created by shayaShav and is hosted on GitHub. The tool is published via npm trusted publishing with provenance attestations and signed tags. It is confined to the session store and does not access project source code or other files unless explicitly told to retrieve an image to a specific path. By default, there are zero outbound network calls. The codebase is small, consisting of a few TypeScript files, with no telemetry, analytics, or spawned processes. The tool is available as a CLI, a library, and an HTTP server, providing flexibility for different use cases. A public instance is available at https://shaya.cloud/flatten-mcp for use with various platforms without local installation.