What File Types Does Caveman Compression Target? Markdown-First Architecture Explained

Caveman compression exclusively targets Markdown files with the .md extension, rewriting them in-place while preserving code blocks and URLs, and creating .original.md backups alongside the compressed versions.

The Caveman toolset provides specialized compression capabilities designed specifically for documentation workflows. According to the JuliusBrussee/caveman repository source code, the caveman-compress skill focuses entirely on Markdown files, offering intelligent text compression that maintains the structural integrity of technical documents while reducing prose verbosity.

Primary Target: Markdown (.md) Files

The caveman-compress skill is engineered to process Markdown files exclusively. As defined in skills/caveman-compress/SKILL.md, the system looks for files bearing the .md extension—such as README.md, CLAUDE.md, or todos.md—and applies compression algorithms that reduce word count without corrupting document structure.

This Markdown-centric approach reflects Caveman's design philosophy: documentation files often contain verbose explanatory text that can be condensed while preserving technical accuracy. The skill reads the specified Markdown document, transforms its prose content, and writes the result back to the original file path.

How the Compression Engine Handles Markdown

The implementation in skills/caveman-compress/scripts/compress.py demonstrates sophisticated content awareness. When processing Markdown files, the compression algorithm specifically:

• Preserves code blocks (fenced and indented)
• Maintains URLs and hyperlink integrity
• Keeps file paths and directory references intact
• Protects identifiers such as variable names and function signatures

This selective compression ensures that while explanatory prose gets condensed, the executable and navigable elements of documentation remain unchanged and functional.

Backup Creation Pattern

Caveman follows a non-destructive workflow that protects your original content. When executing compression, the system writes the transformed content back to the source file while simultaneously creating a backup with the suffix .original.md in the same directory. For example, processing notes.md generates notes.md.original.md as an immutable reference point.

Using the caveman-compress CLI

The command-line interface accepts file paths directly and operates transparently on the filesystem:

# Compress a local Markdown file

caveman-compress path/to/notes.md

# -> rewrites notes.md and creates notes.md.original.md as a backup

When using the Opencode plugin inside a model session, the slash command provides identical functionality:

# Using the Opencode plugin inside a model session

/caveman-compress notes.md

# (the same effect as the CLI command)

Both methods invoke the same Python backend that handles file detection, compression, and backup generation.

Secondary Compression: MCP Server Descriptions

While caveman-compress handles file-based operations, the repository also contains caveman-shrink, an MCP server implementation that operates on in-memory data structures rather than files. Located in src/mcp-servers/caveman-shrink/index.js, this component compresses description fields within MCP responses—specifically targeting tools, prompts, and resources arrays in JSON responses.

This distinction is critical: caveman-shrink does not process file types but rather manipulates API response payloads. When integrating Caveman as MCP middleware, description strings undergo automatic compression to reduce token usage in model contexts:

// Within a custom MCP server, description fields are compressed automatically
const transformed = compressDescriptionsInPlace(response, ['description']);

Summary

• Caveman compression targets only Markdown files (.md extension) through the caveman-compress skill.
• Backup files use the .original.md suffix to preserve pre-compression states.
• Content preservation rules protect code blocks, URLs, file paths, and identifiers during Markdown processing.
• Implementation files include skills/caveman-compress/SKILL.md for command definitions and skills/caveman-compress/scripts/compress.py for the compression logic.
• caveman-shrink handles JSON description fields in MCP responses but does not process files on disk.

Frequently Asked Questions

Does Caveman compression work on file types other than Markdown?

No. The caveman-compress skill is specifically designed for Markdown files only. According to the source code in skills/caveman-compress/SKILL.md, the system explicitly filters for .md extensions and does not implement handlers for other formats such as .txt, .rst, or code files.

What happens to my original file when using caveman-compress?

Caveman creates a non-destructive backup before modifying your content. When you run the compression command on a file like document.md, the system writes the compressed version to document.md while saving the original content as document.md.original.md in the same directory.

How does caveman-shrink differ from caveman-compress?

While caveman-compress operates on Markdown files stored on disk, caveman-shrink functions as an MCP server middleware that compresses description fields in JSON API responses. As implemented in src/mcp-servers/caveman-shrink/index.js, it processes in-memory data structures rather than files, targeting fields within tools, prompts, and resources arrays.

Which Markdown elements are preserved during compression?

The compression algorithm in skills/caveman-compress/scripts/compress.py specifically preserves technical references including code blocks (both fenced and indented), URLs and hyperlinks, file system paths, and programming identifiers. Only explanatory prose undergoes compression, ensuring the document remains functional and navigable after processing.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}