What Kind of Projects Can Be Built with Caveman: A Complete Guide to Token-Efficient AI Development

Caveman is a compression skill that can be attached to any AI-coding agent to reduce output tokens by approximately 65% while preserving code and error messages byte-for-byte, making it ideal for building custom assistants, microservices, and memory-efficient bots.

If you are exploring what kind of projects can be built with Caveman, the JuliusBrussee/caveman repository offers a modular architecture designed to minimize token usage across the entire AI development stack. Unlike a standalone application, Caveman functions as an interchangeable skill system that integrates with over 30 supported agents including Claude Code, Gemini, Cursor, and Windsurf.

Understanding Caveman's Three-Layer Architecture

Caveman is not a monolithic framework but a set of three distinct components that can be embedded individually or combined. Each component targets a different layer of the AI interaction stack, allowing you to choose the right abstraction for your specific project requirements.

The Skill/Plugin Layer

The skill/plugin is a prompt-based system that instructs agents to drop filler words and retain only essential code, commands, and errors. When attached to an agent via npx skills add JuliusBrussee/caveman -a <agent>, it acts as a single-turn rewriter that transforms verbose LLM outputs into concise "caveman-speak" immediately upon generation.

The Command Interface Layer

The command interface provides runtime control through slash commands declared in commands/caveman.md. These include:

• /caveman [lite|full|ultra|wenyan] – Toggle between compression intensity levels
• /caveman-stats – Display token savings with optional --share flag for social sharing
• /caveman-compress – Shrink long-term memory files before sessions begin

This layer is implemented in src/hooks/caveman-stats.js, which parses session logs and attributes tokens to specific compression modes to produce human-readable statistics.

The MCP Middleware Layer

caveman-shrink, located at src/mcp-servers/caveman-shrink/index.js, is a Node.js proxy that sits between an MCP server and the model. It intercepts tool, prompt, and resource listings and compresses their description fields before they reach the model, reducing the token cost of every downstream request in API-driven architectures.

Four Project Types You Can Build with Caveman

Depending on which architectural layer you target, you can build distinctly different categories of token-efficient AI projects.

Custom AI Assistants

The most straightforward application involves converting existing agents into terse, high-density assistants. By installing the skill with npx skills add JuliusBrussee/caveman -a claude (or any supported agent), you create a caveman-mode assistant that maintains the agent's reasoning capabilities while eliminating verbose explanations.

This approach works for single-turn interactions where you want immediate, dense outputs without changing the underlying model or infrastructure.

LLM-Powered Microservices

For service-oriented architectures, wrap your MCP servers with caveman-shrink to build token-efficient microservices. When you expose a model-driven API—such as a code-assistant service or specialized tooling endpoint—the middleware automatically compresses tool descriptions before they are transmitted to the model.

This reduces the per-request token cost for every API call your service handles, directly lowering operational expenses when running at scale.

Long-Running Bots with Persistent Memory

Implement memory-efficient persistent agents by combining the command interface with file compression. Use /caveman-compress on markdown files containing project notes or conversation history before starting new sessions.

Since the compression preserves technical substance while reducing file size, future sessions load pre-compressed context that consumes fewer tokens forever. This is critical for bots that maintain state across extended workflows or multi-day operations.

Full-Stack Token-Reduction Suites

Advanced projects can combine Caveman with its ecosystem siblings (caveman-code, cavemem, cavekit, cavegemma) to create comprehensive token-reduction pipelines. These suites shrink not only the agent's immediate output but also its memory storage, build loops, and even underlying model weights.

This architecture is documented in docs/HONEST-NUMBERS.md, which explains the methodology for calculating token savings across the entire stack.

Implementation Examples

Below are practical implementations for each project type.

Install the skill for Claude Code:

npx skills add JuliusBrussee/caveman -a claude
/caveman full

Toggle compression levels at runtime:

# Minimal output mode

/caveman lite

# Maximum compression

/caveman ultra

Generate token statistics:

# Detailed report

/caveman-stats

# Single-line shareable format

/caveman-stats --share

Configure MCP middleware in your server config:

{
  "mcpServers": {
    "fs-shrunk": {
      "command": "npx",
      "args": [
        "caveman-shrink",
        "npx",
        "@modelcontextprotocol/server-filesystem",
        "/my/project"
      ]
    }
  }
}

Compress long-term memory files:

# Pre-compress notes for future sessions

caveman-compress ./docs/PROJECT_NOTES.md

Summary

Caveman enables four distinct categories of token-efficient AI projects:

• Custom assistants via the skill/plugin system that attaches to existing agents
• Microservices using caveman-shrink middleware to reduce API token costs
• Persistent bots leveraging /caveman-compress to minimize long-term memory overhead
• Full-stack suites combining Caveman with ecosystem tools for end-to-end compression

The architecture spans commands/caveman.md for runtime control, src/hooks/caveman-stats.js for analytics, and src/mcp-servers/caveman-shrink/index.js for service-layer optimization.

Frequently Asked Questions

What agents are compatible with Caveman skills?

Caveman supports more than 30 AI-coding agents including Claude Code, Gemini, Cursor, Windsurf, Cline, and Copilot. The skill installs via npx skills add JuliusBrussee/caveman -a <agent_name> and activates immediately without modifying the underlying model weights.

How much token reduction can I expect in production?

According to the source analysis and benchmarks in the repository, Caveman reduces output tokens by approximately 65% on average while preserving code, commands, and error messages byte-for-byte. The exact savings depend on the compression level selected (lite, full, ultra, or wenyan).

Can I use Caveman with my existing MCP servers?

Yes. The caveman-shrink middleware (implemented in src/mcp-servers/caveman-shrink/index.js) acts as a transparent proxy that wraps any existing MCP server. It intercepts and compresses description fields before they reach the model, making it compatible with standard filesystem, database, or custom tool servers without requiring changes to their implementations.

Does Caveman modify my original files when compressing memory?

No. When using caveman-compress on files like ./docs/PROJECT_NOTES.md, the tool creates compressed versions or modifies copies specifically for session loading. The original documentation remains intact, allowing you to maintain human-readable source material while the agent consumes token-optimized versions during runtime.

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