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

> Caveman compression targets only Markdown files with the .md extension. Learn how it rewrites them in-place, preserving code blocks and URLs.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: architecture
- Published: 2026-07-07

---

**Caveman compression exclusively targets Markdown files with the `.md` extension**, rewriting them in-place while preserving code blocks and URLs, and creating [`.original.md`](https://github.com/JuliusBrussee/caveman/blob/main/.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`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/SKILL.md), the system looks for files bearing the `.md` extension—such as [`README.md`](https://github.com/JuliusBrussee/caveman/blob/main/README.md), [`CLAUDE.md`](https://github.com/JuliusBrussee/caveman/blob/main/CLAUDE.md), or [`todos.md`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/.original.md) in the same directory. For example, processing [`notes.md`](https://github.com/JuliusBrussee/caveman/blob/main/notes.md) generates [`notes.md.original.md`](https://github.com/JuliusBrussee/caveman/blob/main/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:

```bash

# 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:

```bash

# 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`](https://github.com/JuliusBrussee/caveman/blob/main/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:

```javascript
// 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`](https://github.com/JuliusBrussee/caveman/blob/main/.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`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/SKILL.md) for command definitions and [`skills/caveman-compress/scripts/compress.py`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/document.md), the system writes the compressed version to [`document.md`](https://github.com/JuliusBrussee/caveman/blob/main/document.md) while saving the original content as [`document.md.original.md`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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.