What Is caveman-code and How It Differs from the caveman Project

caveman-code is a full-stack terminal coding agent that compresses every generated artifact—including prompts, responses, and code—while the caveman project is merely a conversational skill that makes an existing LLM agent's speech more concise.

The caveman repository (JuliusBrussee/caveman) provides two distinct solutions for reducing token consumption in LLM workflows. While both aim to lower costs, they operate at fundamentally different architectural layers. Understanding these distinctions ensures you choose the right tool for your workflow.

What Is caveman-code?

caveman-code is a self-contained, global npm package that functions as a complete coding agent. Unlike plugins that modify existing behaviors, it operates as its own process with built-in token compression heuristics applied to every interaction.

According to the source documentation, caveman-code represents "the whole agent, end to end" and achieves approximately 2× fewer tokens on identical tasks by shrinking everything that the agent generates—prompts, configuration files, and source code—before it ever reaches the model.

Key Characteristics

• Scope: End-to-end agent lifecycle with compression at every layer
• Installation: Global npm package (npm install -g @juliusbrussee/caveman-code)
• Runtime: Direct CLI execution (caveman-code run)
• Token Savings: ~50% reduction across all generated artifacts

How the caveman Skill Differs

The caveman skill found in the current repository is a lightweight plugin designed to drop into an existing LLM-agent workspace. Its sole purpose is to make the agent's spoken output more concise by removing filler words while strictly preserving code blocks, commands, and error messages.

In src/tools/caveman-init.js, the skill initializes by inserting a tiny flag file at the start of a session. This flag signals the host agent to automatically speak "caveman-style" without requiring manual activation. The low-level hook in bin/lib/opencode-agent.js handles the flag file creation, while commands/caveman.md documents the user-facing /caveman toggle command.

Key Characteristics

• Scope: Only the agent's conversational text output
• Installation: Skill file dropped via install.sh script
• Runtime: Activated by flag file or /caveman command
• Token Savings: ~46% per session (text output only)

Architectural Comparison

Feature	caveman Skill	caveman-code
Architecture	Plugin/skill for existing agents	Standalone full-stack agent
Compression Target	Spoken responses only	Prompts, code, configs, and responses
Activation	Automatic via flag file or /caveman	Always-on within caveman-code run
Package Manager	Bash installer	npm (@juliusbrussee/caveman-code)
Entry Point	src/tools/caveman-init.js	package.json CLI definition

Installation and Usage Examples

Installing the caveman Skill

Drop the skill into a Claude-based or compatible agent workspace:

# Download and execute the installer

curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash

After installation, toggle brevity mode manually:

/caveman          # Toggle caveman-style output for current chat

/caveman-stats    # Display session token savings

Installing caveman-code

Install the full agent globally as referenced in the package.json configuration:

# Global npm installation

npm install -g @juliusbrussee/caveman-code

# Start the compressed coding session

caveman-code run

Because caveman-code runs as its own process with compression logic residing in src/agent.js, you never need to issue a /caveman command—the agent automatically applies token-saving heuristics to all generated output.

Key Source Files

Understanding the implementation requires examining specific files from each project:

caveman Skill (Current Repository):

• src/tools/caveman-init.js – Entry point that initializes the skill session
• bin/lib/opencode-agent.js – Low-level hook writing the activation flag file
• commands/caveman.md – Command documentation for /caveman and /caveman-stats

caveman-code (Separate Package):

• README.md – High-level description and installation instructions
• package.json – Defines the CLI entry point (bin/caveman-code.js)
• src/agent.js – Core logic compressing prompts, responses, and generated files

Summary

• caveman-code is a standalone terminal agent that provides ~2× token reduction by compressing every aspect of the coding workflow.
• caveman is a conversational skill that reduces spoken output by ~46% without touching code or commands.
• Use the skill when you have a preferred agent and only need terse speech; use caveman-code when you want a completely token-efficient end-to-end coding environment.
• The skill activates via flag files in src/tools/caveman-init.js, while caveman-code runs as a global npm process with its own src/agent.js runtime.

Frequently Asked Questions

Can I use caveman-code alongside my existing Claude or Cursor setup?

No. caveman-code is designed as a replacement rather than an augmentation. It runs as its own process (caveman-code run) with its own src/agent.js core, whereas the caveman skill is explicitly built to drop into existing agent workspaces via install.sh without replacing the underlying runtime.

Will caveman-code modify my actual source code files on disk?

Yes, by design. Unlike the caveman skill—which explicitly avoids touching code, commands, or error messages—caveman-code compresses everything the agent generates, including the code it writes to your filesystem. This achieves the ~2× token savings but requires trust in the compression heuristics implemented in the agent's core logic.

How do I check token savings in caveman-code versus the caveman skill?

For the caveman skill, use the /caveman-stats command documented in commands/caveman.md to see per-session savings. For caveman-code, token efficiency is built into the runtime architecture defined in package.json and src/agent.js; the savings are structural (~2× fewer tokens) rather than measured per command, as compression happens automatically at every generation step.

Is caveman-code open source like the caveman skill?

Yes. Both projects are open source under the JuliusBrussee organization. The caveman skill resides in the current repository with its entry point at src/tools/caveman-init.js, while caveman-code maintains its own repository with the CLI entry point defined in package.json and core logic in src/agent.js.

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