Output Token Savings vs Input Token Savings in Caveman: Complete Technical Guide

Output token savings compress the AI model's generated responses by approximately 65% using terse "caveman-speak" rules, while input token savings reduce memory file sizes by roughly 46% through the caveman-compress command, with both metrics exposed via the /caveman-stats hook.

Caveman (JuliusBrussee/caveman) is an open-source token optimization framework for Claude Code that implements two distinct compression strategies to reduce API costs. Understanding the difference between output token savings and input token savings is critical for optimizing your AI-assisted development workflow, as each mechanism targets a different phase of the model interaction lifecycle.

How Output Token Savings Work in Caveman

Output token savings target the text generated by the AI model during each turn of conversation. This mechanism operates by rewriting the model's natural language responses into a compressed dialect while preserving code integrity.

The Caveman Skill System Prompt

In skills/caveman/SKILL.md, the framework defines a system-prompt skill that instructs the model to communicate in "caveman-speak." The rules explicitly direct the model to drop articles, filler words, pleasantries, and hedging language while leaving code blocks, symbols, and error strings untouched. This transformation happens at the response generation layer, meaning every token the model outputs is filtered through these compression rules before reaching the user.

Token Reduction Metrics

According to benchmarks documented in docs/HONEST-NUMBERS.md, the output token savings mechanism achieves an average 65% reduction in generated tokens. The skill measures this reduction on-the-fly by comparing the compressed response against a baseline estimate of what the standard verbose response would have consumed. These statistics are accumulated throughout the session and remain volatile until the conversation ends.

How Input Token Savings Work in Caveman

Input token savings target the context window consumption by compressing persistent memory files that the model reads at the start of each session or turn.

The caveman-compress Command

Implemented in skills/caveman-compress/SKILL.md, the caveman-compress command preprocesses any markdown or text file using the same token-dropping rules applied to output compression. When you execute this command on a project memory file like CLAUDE.md, the system creates a backup at <file>.original.md and overwrites the original with the compressed version.

Persistent File Compression

Because memory files are read into the context window on every session initialization, shrinking them yields permanent input token savings. The compression achieves approximately 46% reduction in file size, directly translating to proportionally fewer input tokens consumed when the model ingests these files. Unlike output savings, which reset each session, input savings persist across all future interactions with the compressed file.

Measuring Token Savings with caveman-stats

The caveman-stats skill provides real-time visibility into both types of savings, aggregating data from the Claude Code session logs to present accurate token accounting.

Real-time Session Analytics

Documented in skills/caveman-stats/README.md, this skill computes actual input and output token counts by analyzing the session history. It estimates what the output token count would have been without Caveman compression, then calculates the difference between the actual compressed output and the theoretical baseline.

The caveman-mode-tracker Hook

The actual reporting mechanism resides in plugins/caveman/agents/caveman-mode-tracker. When you invoke /caveman-stats, this hook intercepts the command and formats the statistics into a readable report:

# Example output from /caveman-stats

Input:   12,304 tokens
Output:   3,891 tokens (caveman)
Baseline: 11,247 tokens
Saved:    7,356 tokens (~65% output saving)

Net Impact and Trade-offs

While both mechanisms reduce token consumption, they operate at different stages and carry distinct overhead costs that affect the overall session efficiency.

The Input Token Overhead

The caveman skill itself adds approximately 1,000 to 1,500 input tokens per turn because the model must ingest the system prompt rules defining the compression grammar. This overhead is constant regardless of the output length, making the skill most cost-effective during output-heavy workflows.

Session-Level Efficiency

Per the analysis in docs/HONEST-NUMBERS.md, the net savings across a typical session range from 14% to 21% when output volume is high. On terse Q&A interactions where the model generates minimal text, the input overhead can exceed the output savings, resulting in a net negative token impact. However, for code generation and explanation tasks where responses are verbose, the 65% output reduction far outweighs the fixed input cost.

Practical Usage Examples

Enable output token compression for the current session:

/caveman

Compress a memory file to reduce input tokens for future sessions:

caveman-compress CLAUDE.md

# Creates CLAUDE.md.original.md as backup

Query the current session statistics to verify savings:

/caveman-stats

Summary

• Output token savings reduce the model's generated text by approximately 65% using the caveman skill's system prompt rules, applied dynamically to each response.
• Input token savings reduce persistent file sizes by roughly 46% using the caveman-compress command, permanently shrinking memory files like CLAUDE.md.
• The caveman-stats hook and caveman-mode-tracker plugin provide real-time measurement of both metrics by analyzing session logs against baseline estimates.
• Both mechanisms preserve code blocks and symbols while removing natural language filler, with backup files (.original.md) protecting against data loss during compression.
• Net session savings of 14-21% are typical for output-heavy workflows, though the ~1-1.5k input token overhead per turn can exceed benefits during brief interactions.

Frequently Asked Questions

What is the difference between output and input token savings in Caveman?

Output token savings occur when the model generates text, compressing the AI's replies by 65% through terse "caveman-speak" rules defined in skills/caveman/SKILL.md. Input token savings occur when the model reads files, achieved by permanently compressing memory files via caveman-compress to reduce the context window by approximately 46%. One targets generation; the other targets ingestion.

How much does Caveman reduce tokens by?

According to docs/HONEST-NUMBERS.md, output compression achieves ~65% reduction in generated tokens, while file compression achieves ~46% reduction in input file size. However, the caveman skill adds roughly 1,000-1,500 input tokens per turn as overhead, yielding net session savings of 14-21% for typical coding workflows.

Does Caveman compression affect code blocks?

No. Both the output skill (skills/caveman/SKILL.md) and the compression command (skills/caveman-compress/SKILL.md) explicitly preserve code blocks, symbols, error strings, and technical identifiers. The compression targets only natural language filler, articles, and hedging words, ensuring that functional code remains intact and executable.

What is the overhead cost of enabling Caveman mode?

Enabling Caveman mode via /caveman requires the model to ingest the system prompt rules, which consumes approximately 1,000 to 1,500 additional input tokens per turn. This fixed cost makes the mode most efficient for output-heavy sessions (long explanations, code generation) where the 65% output savings outweigh the input overhead, and less efficient for brief Q&A exchanges.

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