What File Types Can caveman-compress Process and Which Are Explicitly Excluded

caveman-compress processes natural-language documentation files including .md, .txt, .rst, .typ, and .tex while explicitly excluding code files, configuration files, and backup copies to preserve project integrity.

The caveman-compress skill in the JuliusBrussee/caveman repository is designed to shrink natural-language project-memory files while leaving code-related content untouched. Understanding what file types can caveman-compress process and which are explicitly excluded is essential for maintaining clean documentation without risking your source code. This compression utility uses a strict whitelist and blacklist system defined in its source code to determine which files receive token-saving compression.

Supported File Types for caveman-compress

According to the skills/caveman-compress/README.md, the skill maintains a specific whitelist of natural-language file formats that undergo compression. These formats are chosen because they typically contain prose, documentation, and specifications rather than executable code.

Document Formats

The skill processes the following document extensions:

• .md (Markdown files)
• .txt (Plain text files)
• .rst (reStructuredText files)
• .typ and .typst (Typst markup files)
• .tex (LaTeX source files)

When you run /caveman-compress against any of these files, the tool creates a compressed version alongside an original backup (e.g., CLAUDE.md becomes CLAUDE.original.md after compression).

Extension-less Natural-Language Files

The compression logic also handles extension-less natural-language files that contain project documentation or notes without traditional file extensions. These are identified by content analysis rather than extension matching, ensuring that plain text documents without standard naming conventions still benefit from compression.

Excluded File Types and Backup Protection

The caveman-compress skill implements strict exclusion rules to prevent accidental modification of code or configuration files. These exclusions are hardcoded in the validation logic found in src/mcp-servers/caveman-shrink/compress.js.

Code and Configuration Files

The following file types are explicitly skipped to preserve code integrity:

• .py (Python source files)
• .js (JavaScript files)
• .ts (TypeScript files)
• .json (JSON configuration files)
• .yaml (YAML configuration files)

Attempting to compress these files results in immediate rejection with no compression performed, ensuring that your codebase remains unchanged and syntactically valid.

Backup File Protection

The skill also excludes *.original.md files—automatically generated backups created during previous compression runs. This prevents recursive compression of already-compressed backups and protects the original content hierarchy. If you attempt to compress a .original.md file, the command ignores the request to avoid data corruption.

How Compression Logic Handles File Types

The file-type validation occurs in src/mcp-servers/caveman-shrink/compress.js, which implements the core compression engine. This JavaScript module validates file extensions against the whitelist before processing and checks for the .original.md suffix to prevent backup compression.

The command registration and documentation reside in src/plugins/opencode/commands/caveman-compress.md, which exposes the /caveman-compress command to the OpenCode plugin system. Together, these files enforce the compression boundaries that distinguish natural-language content from executable code.

Practical Usage Examples

Compress supported documentation files using the /caveman-compress command:

# Compress a markdown file (creates CLAUDE.md and CLAUDE.original.md)

/caveman-compress CLAUDE.md

# Compress a plain-text notes file

/caveman-compress docs/notes.txt

# Compress a reStructuredText specification

/caveman-compress docs/spec.rst

The following commands demonstrate excluded file types that will be ignored:

# Skipped: Python source files are excluded

/caveman-compress src/app.py

# Skipped: Backup files are protected from re-compression

/caveman-compress README.original.md

# Skipped: Configuration files remain untouched

/caveman-compress config.yaml

Summary

• caveman-compress processes natural-language files: .md, .txt, .rst, .typ, .typst, .tex, and extension-less text files.
• caveman-compress excludes code and configuration files: .py, .js, .ts, .json, .yaml.
• Backup protection prevents compression of *.original.md files to preserve original content.
• Source implementation resides in skills/caveman-compress/README.md and src/mcp-servers/caveman-shrink/compress.js.

Frequently Asked Questions

Can caveman-compress handle HTML documentation files?

No. According to the source code in skills/caveman-compress/README.md, HTML files are not included in the supported file type whitelist. The skill focuses specifically on markdown, plain text, reStructuredText, Typst, and LaTeX formats. HTML files, even when containing documentation, are treated as excluded code-adjacent files.

What happens if I try to compress a Python file with caveman-compress?

The command will skip the file entirely with no compression performed. The validation logic in src/mcp-servers/caveman-shrink/compress.js explicitly checks for .py extensions and other code file types, immediately rejecting them to prevent source code modification. You will not receive a compressed output or backup file.

Does caveman-compress create backups of compressed files?

Yes. When you compress a supported file like CLAUDE.md, the skill automatically creates CLAUDE.original.md containing the uncompressed version. This backup file is then explicitly excluded from future compression attempts to prevent recursive processing and data loss.

Can I compress files without file extensions using caveman-compress?

Yes. The skill supports extension-less natural-language files according to the documentation in skills/caveman-compress/README.md. These files are processed based on content analysis rather than extension matching, allowing you to compress plain text documentation that lacks standard file extensions.

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