Caveman's Privacy Architecture: Does It Send Telemetry or Phone Home?

Caveman is a completely offline-first tool with zero telemetry, no phone-home mechanisms, and no external backend—100% of data processing happens locally after installation.

The JuliusBrussee/caveman repository implements a privacy-first architecture designed to keep AI-assisted development workflows strictly on-device. Understanding Caveman's privacy architecture is essential for security-conscious developers and organizations that require guarantees their code, session data, and usage patterns never leave the local machine.

Core Privacy Guarantees

Caveman's security model rests on three architectural pillars that ensure complete data sovereignty:

Zero Telemetry

The codebase contains no analytics, crash reporting, or usage metrics. According to SECURITY.md, the security policy explicitly states: "Caveman has no telemetry. Zero." After installation, the application never contacts any external server for logging, updates, or tracking purposes.

Local-Only Execution

All operational logic executes strictly within the local environment. The core skill definition resides in skills/caveman/SKILL.md as a plain markdown prompt containing no executable code. Hooks located in src/hooks/*.js (or bin/lib/*.js) perform exclusively file-system reads and writes—no fetch, http, or https calls exist in these modules.

Self-Contained Runtime

Every utility operates on local resources only:

• /caveman-stats reads Claude session JSONL logs from disk to compute token counts and price estimates
• caveman-shrink wraps a locally-configured MCP server without initiating independent network traffic
• /caveman-compress rewrites user-specified Markdown files in place and stores backups locally

Install-Time Network Activity (One-Time Only)

Network traffic occurs exclusively during the initial installation phase. After setup, "nothing in caveman touches the network" according to SECURITY.md.

Step	Network Activity	Source Location
Installer script	Fetches installer shim from raw.githubusercontent.com	INSTALL.md
NPM execution	Downloads repository via npx -y github:JuliusBrussee/caveman	INSTALL.md
Agent plugins	Installs agent-specific CLIs (Claude, Gemini, etc.)	INSTALL.md
Fallback mode	Downloads hook files from immutable GitHub tags with SHA-256 verification	INSTALL.md

The installer writes files to local directories such as ~/.claude/, agent-specific config paths, and the current working directory, but never transmits data outward.

Architectural Components

Understanding the specific components demonstrates how Caveman maintains its privacy guarantees at the code level.

Skill Definition (Markdown Only)

The primary skill file at skills/caveman/SKILL.md contains only instructional markdown. Unlike tools that execute remote code blobs, Caveman parses static documentation that instructs local AI agents without runtime downloads.

Hooks (Pure Local Scripts)

Hook scripts in src/hooks/*.js handle session management, status-line updates, and flag file operations. These Node.js modules import only local filesystem utilities (fs, path) and contain no network client libraries. They read from and write to local caches, session logs, and configuration files exclusively.

Utility Commands (Local Processing)

Each command-line tool processes data without external dependencies:

• Stats command (caveman-stats): Aggregates ~/.claude/session.jsonl data for local cost analysis
• Compress command (caveman-compress): Transforms Markdown files using local rewrite rules and creates .original.md backups
• Shrink middleware (caveman-shrink): Intercepts MCP server I/O locally, compressing payloads without API calls

Verifying Privacy Locally

You can confirm Caveman's offline behavior using these practical examples:

Run the stats command to analyze local session data:

caveman-stats

This reads ~/.claude/session.jsonl and prints token counts and estimated costs. No network request is performed.

Compress a Markdown file locally:

caveman-compress path/to/document.md

This rewrites document.md in place, creates document.original.md as a backup, and updates the local status-line file. All actions remain confined to the filesystem.

Use the shrink middleware with a local MCP server:

caveman-shrink --input input.mcp --output output.mcp

This spawns your locally-configured MCP server and compresses its output. No external API calls are initiated.

Install completely offline to eliminate network access:

git clone https://github.com/JuliusBrussee/caveman.git
cd caveman
node bin/install.js --offline

The --offline flag forces the installer to copy files from the local clone, avoiding any network access while still writing to local config directories.

Summary

Caveman's privacy architecture ensures complete data sovereignty through:

• Zero telemetry explicitly guaranteed in SECURITY.md with no analytics or crash reporting
• Local-only execution where skills are markdown-based and hooks perform only filesystem I/O
• Self-contained runtime with all utilities (caveman-stats, caveman-compress, caveman-shrink) processing data exclusively on local disk
• One-time network activity restricted to installation fetches from documented GitHub endpoints

Frequently Asked Questions

Does Caveman collect any usage analytics or crash reports?

No. Caveman collects zero telemetry. The security policy explicitly states "Caveman has no telemetry. Zero." There are no analytics endpoints, crash reporting mechanisms, or usage statistics gathering in any component of the codebase.

Can Caveman function entirely offline after installation?

Yes. Once installed, Caveman operates completely offline. All features including session statistics (caveman-stats), file compression (caveman-compress), and MCP middleware (caveman-shrink) process data using only local filesystem operations. The tool reads local logs, writes local backups, and invokes locally-configured servers without network calls.

What network activity occurs during Caveman installation?

Network requests occur only during the initial installation phase. The installer fetches the script from raw.githubusercontent.com, downloads the repository via npx, and optionally retrieves agent-specific plugins. These are one-time fetches documented in INSTALL.md. After installation, the SECURITY.md policy confirms that "nothing in caveman touches the network."

How can I verify that Caveman isn't making hidden network requests?

Audit the source code in src/hooks/*.js and bin/lib/*.js to confirm no fetch, http, or https imports exist. Run caveman-stats or caveman-compress with network monitoring tools (such as netstat or Wireshark) to verify zero outbound connections. Alternatively, use the --offline flag with bin/install.js to install from a local git clone, eliminating even the initial network fetches.

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