# Security Considerations When Using Caveman with Sensitive Code: Local-First Architecture Explained > Learn security considerations for using Caveman with sensitive code. Explore local-first architecture, input validation, and prompt injection risks for JuliusBrussee/caveman. - Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman) - Tags: security-guide - Published: 2026-07-12 --- **Caveman operates entirely offline with zero telemetry after installation, minimizing data exfiltration risks, but requires strict input validation when using the `/caveman-compress` command and awareness of prompt injection vectors.** When working with proprietary or classified codebases, understanding the **security considerations when using Caveman with sensitive code** is critical for maintaining compliance and data sovereignty. The **JuliusBrussee/caveman** repository addresses these requirements through a **local-first architecture** that never transmits source code to external APIs, as documented in [`SECURITY.md`](https://github.com/JuliusBrussee/caveman/blob/main/SECURITY.md) and reinforced in the core skill definition at [`skills/caveman/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md). ## Zero Telemetry and Local-Only Processing Caveman’s security model guarantees **zero telemetry** following the initial installation. According to [`SECURITY.md`](https://github.com/JuliusBrussee/caveman/blob/main/SECURITY.md), the skill and its hooks never make HTTP requests after setup, ensuring that code, prompts, and generated outputs remain confined to the local machine. This **network isolation** makes the tool suitable for highly regulated environments. Only the installer scripts ([`install.sh`](https://github.com/JuliusBrussee/caveman/blob/main/install.sh) or `install.ps1`) contact GitHub to fetch the repository; thereafter, the agent runs completely offline. Verify that your installation is complete, then disconnect from the network to ensure absolute privacy. ## File System Safety and the Compress Command The `/caveman-compress` command provides token optimization by rewriting markdown files, but its file system interactions require careful handling. ### Backup Creation and In-Place Rewriting Implemented in [`skills/caveman-compress/scripts/compress.py`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/scripts/compress.py), the command rewrites **named** files in place while automatically creating a [`.original.md`](https://github.com/JuliusBrussee/caveman/blob/main/.original.md) backup. This protects against accidental data loss but executes with the user's file permissions. Always inspect the backup before deleting it, and maintain version control as a secondary safety net. ### Restricted Write Scope The command can only affect files you explicitly specify in the argument; it will not traverse directories or touch unrelated configuration files. The [`SECURITY.md`](https://github.com/JuliusBrussee/caveman/blob/main/SECURITY.md) file explicitly documents this limitation under the Snyk "High Risk" assessment for `caveman-compress`, confirming that the tool lacks the capability to perform wildcard or recursive overwrites. Double-check the filename argument to prevent accidental overwrites of critical files. ## Prompt Injection and Data Handling Unlike sanitization tools that strip dangerous content, Caveman compresses **only the style** of the agent’s output. As defined in [`SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/SKILL.md), the tool preserves all technical substance—including code blocks, error strings, and CLI commands—without alteration. This behavior creates a **prompt-injection surface**: any malicious payload or sensitive secret embedded in a user prompt will be echoed verbatim in the output. Do not rely on Caveman to sanitize or redact confidential information. Treat all prompts as untrusted data, and never paste API keys, passwords, or tokens into conversations processed by the tool unless you explicitly control and audit the input. ## Installation Security and Shell Execution Understanding the boundary between the installer and the runtime is essential for deployment security. ### Installer Script Risks The only shell execution occurs during the initial setup via [`install.sh`](https://github.com/JuliusBrussee/caveman/blob/main/install.sh) or `install.ps1`, which fetch the repository from GitHub. For high-security environments, inspect these scripts before execution or deploy from an internal clone using `node bin/install.js` to bypass the network-dependent curl pipe. ### Core Skill Architecture The core skill is a pure markdown prompt with no native code execution capabilities. This **no-shell-execution** policy prevents arbitrary code execution triggered by malicious prompts, limiting the attack surface to the file operations explicitly defined in the skill. ## Enterprise and Air-Gapped Deployment Caveman supports **enterprise and air-gapped use** once the repository is cloned. The tool functions with no hidden backend or dependency on external services, making it viable for environments where any outbound traffic is prohibited. Deploy from an internal mirror and verify that the [`SECURITY.md`](https://github.com/JuliusBrussee/caveman/blob/main/SECURITY.md) policies align with your organization's compliance requirements before enabling the skill for sensitive projects. ## Session Persistence and Audit Trails The mode flag is stored in a local file (typically under `~/.claude/...`) and can be cleared with the `/caveman stop` command. This **session-level persistence** allows security teams to audit which sessions used Caveman and ensures the tool can be completely disabled when handling destructive commands or raw secrets. Periodically remove or rotate the flag file if you require a clean operational slate. ## Practical Security Verification Use the following workflow to verify Caveman’s security posture before processing sensitive code: ```bash # 1. Install from a verified source (air-gapped users should clone first) curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash # 2. Enable Caveman mode /caveman # 3. Process sensitive files (verify backup creation) /caveman-compress docs/architecture.md ls docs/*.original.md # 4. Disable when handling secrets /caveman stop ``` ## Summary - **Zero telemetry** after installation ensures code and prompts never leave the local machine, as guaranteed in [`SECURITY.md`](https://github.com/JuliusBrussee/caveman/blob/main/SECURITY.md). - **Local-only file handling** via `/caveman-compress` creates [`.original.md`](https://github.com/JuliusBrussee/caveman/blob/main/.original.md) backups but requires explicit filename confirmation to prevent overwrites. - **No sanitization** of prompt content means secrets and malicious payloads pass through unchanged; never paste credentials into active sessions. - **Offline capability** supports air-gapped environments when deployed from internal clones using `node bin/install.js`. - **Session persistence** stored in `~/.claude/...` can be audited and cleared with `/caveman stop` to maintain operational security. ## Frequently Asked Questions ### Does Caveman send my code to external APIs? No. According to [`SECURITY.md`](https://github.com/JuliusBrussee/caveman/blob/main/SECURITY.md), Caveman runs entirely locally with zero network calls after installation. The skill processes all data on your machine without transmitting source code, prompts, or outputs to any external service, making it safe for proprietary codebases. ### Can Caveman accidentally overwrite my source files? The `/caveman-compress` command only modifies explicitly named files and automatically creates [`.original.md`](https://github.com/JuliusBrussee/caveman/blob/main/.original.md) backups before rewriting. However, you should verify the filename argument and maintain version control, as the command executes with your user permissions and cannot be restricted by the tool itself. ### Is Caveman safe to use in air-gapped environments? Yes. Once cloned, Caveman functions completely offline with no hidden backend dependencies. Deploy from an internal mirror and run `node bin/install.js` locally to avoid the network-dependent installer scripts, satisfying requirements for highly regulated environments. ### Does Caveman sanitize prompts to remove secrets? No. Caveman compresses only stylistic elements while preserving all technical content verbatim, including potential secrets in code blocks. The tool does not redact or sanitize input data, so never paste sensitive credentials into prompts processed by Caveman.