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

> Discover Caveman privacy architecture and confirm it collects zero telemetry and has no phone-home features. All data processing is 100% local.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: architecture
- Published: 2026-07-07

---

**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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/SECURITY.md).

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

```bash
caveman-stats

```

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

Compress a Markdown file locally:

```bash
caveman-compress path/to/document.md

```

*This rewrites [`document.md`](https://github.com/JuliusBrussee/caveman/blob/main/document.md) in place, creates [`document.original.md`](https://github.com/JuliusBrussee/caveman/blob/main/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:

```bash
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:

```bash
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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/INSTALL.md). After installation, the [`SECURITY.md`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) to install from a local git clone, eliminating even the initial network fetches.