Privacy Implications of Using Caveman: A Complete Local-First Security Analysis

Caveman processes all data locally without telemetry, external API calls, or credential storage, making it safe for air-gapped environments.

Caveman, an open-source compression tool for Claude Code sessions developed by JuliusBrussee, is engineered with a privacy-first architecture that eliminates network egress points. Unlike many AI-assisted developer tools, Caveman operates as a local-only system that never transmits your prompts, code, or session data to remote servers after installation.

No Telemetry or Phone-Home Mechanisms

Caveman is deliberately designed as a plain Markdown prompt with no executable code capable of transmitting data externally. According to the SECURITY.md documentation, the tool contains no telemetry collection mechanisms, usage analytics, or hidden network calls. The core functionality resides in static assets and local JavaScript handlers that perform strictly file-based operations.

Local-Only Data Processing Architecture

All hook scripts located in src/hooks/*.js and status-line utilities perform exclusively local file I/O. A comprehensive audit of the source code confirms zero instances of http, https, or fetch API calls within the runtime components. The system reads and writes only to designated flag files, session logs, and savings files within your local filesystem.

Command-Level Privacy Guarantees

/caveman-stats operates entirely offline by reading Claude Code's local session log at ~/.claude/session.jsonl. The command computes token-savings using hard-coded pricing constants and prints results directly to your terminal. No data is posted to APIs or external analytics services.

/caveman-compress performs in-place file rewriting with local backup creation. When you execute this command on a file like notes.md, the system creates notes.md.original.md as a backup and rewrites the compressed content without contacting external compression services or cloud storage.

MCP Middleware (caveman-shrink) wraps only local MCP servers and never initiates independent network traffic. Any network activity observed originates solely from the wrapped server configuration, not from Caveman itself.

Installation vs. Runtime Network Activity

The only network operations occur during the one-time installation phase. The installer script fetches from raw.githubusercontent.com and retrieves repository assets from their respective registries. After successful installation, Caveman functions completely offline. You can verify this behavior by disconnecting from the network; all commands—including compression, statistics, and mode toggling—continue operating normally.

This architecture supports air-gapped and enterprise environments. Because all assets store locally after installation, you can clone the repository directly to bypass the installer network call entirely, creating a fully offline instance that never connects to external servers.

Verifiable Privacy Surface

You can audit Caveman's privacy claims by examining these specific source files:

• SECURITY.md – Contains the detailed privacy and telemetry audit trail
• bin/lib/settings.js – Handles the local flag file (~/.claude/caveman.flag) that toggles Caveman mode via file system checks
• bin/lib/opencode-agent.js – Implements the /caveman-stats command using only local file I/O operations
• bin/lib/openclaw.js – Manages optional integrations while maintaining local-only execution
• plugins/caveman/assets/*.svg – Visual assets containing no executable code

Practical Verification Examples

Enable Caveman and verify the local flag creation:

# Activate compression mode (creates local flag only)

/caveman

# Verify no network activity occurred

cat ~/.claude/caveman.flag

Check token statistics using only local session data:

# Analyze local session logs offline

/caveman-stats --share

Expected output shows local computation:

[CAVEMAN] ⛏ 12.4k tokens saved (~$0.12)

Compress files with local backup generation:

# Rewrites file locally, creates .original.md backup

/caveman-compress notes.md

No Credential Storage

Caveman never requests, stores, or processes API keys, authentication tokens, or secrets. The tool requires no configuration files containing credentials and maintains no state that could expose sensitive access information.

Summary

• Zero telemetry: No data transmission mechanisms exist in the runtime code
• Local processing: All commands operate on local files in ~/.claude/ and specified workspace directories
• Offline capable: Functions without network connectivity after initial installation
• Auditable source: Privacy guarantees verifiable in SECURITY.md and bin/lib/ handler files
• No credentials: No API keys or tokens required for any functionality

Frequently Asked Questions

Does Caveman send my prompts or code to external servers?

No. Caveman processes everything locally. The tool reads from your local Claude Code session files and writes compressed output to your local filesystem. No HTTP requests, DNS lookups, or socket connections originate from Caveman during normal operation.

Can I use Caveman in an air-gapped or offline environment?

Yes. After installation, Caveman requires no internet connectivity. You can verify this by running /caveman-stats or /caveman-compress while disconnected from the network. For completely offline installation, clone the repository directly from a portable medium instead of using the network-based installer.

What network calls does Caveman make during installation?

The only network activity occurs when downloading the installer script from raw.githubusercontent.com and fetching repository assets. These are standard HTTPS GET requests with no data transmission from your machine. After installation completes, zero network calls are made by any Caveman component.

How can I verify that Caveman isn't transmitting data?

Audit the source files in bin/lib/settings.js and bin/lib/opencode-agent.js to confirm the absence of fetch(), XMLHttpRequest, or Node.js http/https module imports. You can also monitor network activity using tools like nettop or Wireshark while running /caveman-stats or /caveman-compress to confirm no outbound connections occur.

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