Please do not file public GitHub issues for sensitive security vulnerabilities.

• For non-sensitive security concerns, you may open a GitHub issue labeled security.
• For sensitive reports, please email the maintainer directly.

We aim to acknowledge reports within 72 hours and patch confirmed issues as quickly as possible.

Holistic is a local-first developer workflow tool that adds persistence, automation, and optional Git-backed state.

It operates entirely on your machine and within your repository. This document explains what it installs, how it behaves, and the security boundaries you should understand before using it.

Holistic is built around a small set of core security and trust principles:

1. Local-first by default: No telemetry, analytics, or external API calls. Data residency is managed by you.
2. Explicit over implicit: System-modifying operations require intentional setup via bootstrap or repair.
3. Least surprise: Routine commands are read-only and will never silently "fix" or mutate your environment.
4. User control and reversibility: Every artifact installed by Holistic can be inspected and manually removed.
5. Minimal privilege: Operates entirely in user space with no sudo or admin privileges required.
6. Transparency over obscurity: Generated scripts are readable, and hook behavior is clearly marked.
7. Containment by Design: Repository-configured paths are explicitly validated against the repo root to prevent directory traversal (v0.6.5).
8. Integrity by Preservation: Corrupted state files are automatically backed up to prevent silent data loss (v0.6.5).
9. Defense in depth (best effort): Includes automated secret redaction and avoids executing shell commands from untrusted or network-provided input.

Holistic operates on a restrictive trust model to ensure your repository remains a safe environment for both humans and AI agents.

Routine commands (status, resume, diff, search, doctor, serve) are designed to be strictly non-mutating and will not intentionally modify your repository state. If configuration drift or outdated hooks are detected, Holistic will surface warnings rather than automatically repairing them.

Commands that modify state (checkpoint, handoff, start-new, watch) are clearly identified. holistic watch in particular is a background daemon mode that creates checkpoints automatically based on activity thresholds.

System-level changes (writing git hooks, configuring startup daemons, or modifying MCP settings) are restricted to two high-intent commands:

• holistic bootstrap: The primary installation and machine setup command.
• holistic repair: Re-scaffolds local machine helpers if they are deleted or broken.

Both commands require explicit user confirmation (or a --yes flag) before modifying files outside the .holistic/ directory.

Holistic enforces strict repository boundaries for all output paths configured in holistic.repo.json. Any attempt to escape the repository root (e.g., using ../) will be rejected, and the system will fall back to safe default paths. These violations are surfaced as Security Warning findings in holistic doctor.

The Holistic build process (npm run build) uses a staging directory approach. Source code transformations happen only on temporary copies, ensuring the src/ directory is never mutated during compilation.

For privacy-conscious or strict instruction environments, users can enable safeMode in .holistic/config.json. This generates minimal instructions in HOLISTIC.md, reducing prompt injection surface area and focusing on documentation-first interaction.

• Does not execute arbitrary shell commands from untrusted or network-provided input
• Does not silently discard corrupted state (backups are created for auditability)

Holistic installs a background daemon that runs while your machine is on to capture session snapshots.

• Windows: Writes a .cmd file to %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\
• macOS: Writes a .plist to ~/Library/LaunchAgents/
• Linux: Writes a .service to ~/.config/systemd/user/

These are standard user-space autostart mechanisms and do not require admin privileges.

• Holistic-generated PowerShell scripts use -ExecutionPolicy RemoteSigned.
• This allows locally-generated scripts to run without changing global policy. Holistic does not use Bypass or Hidden window styles.

• Holistic can push session state to a hidden ref: refs/holistic/state.
• Privacy Mode Enforcement: This is disabled by default. When portableState is false, all generated sync scripts and hooks contain early-exit guards to prevent any accidental remote traffic.

Holistic may install managed Git hooks (e.g., pre-push, post-commit).

• Safety guarantees: Hooks are clearly marked as HOLISTIC-MANAGED. Existing user-managed hooks are never overwritten.

Holistic supports configurable logging levels to prevent session metadata from leaking into system-level logs (e.g., Claude Desktop logs):

• off: No session data is sent to the UI.
• minimal: (Default) Only generic "Session Active" notifications are sent.
• default: Full session titles and goals are sent for maximum context.

Holistic performs basic automated redaction of sensitive patterns identified during development and testing.

• JWTs: Complete scrubbing of JSON Web Tokens.
• Cloud Keys: AWS Access Key IDs (AKIA...).
• Tokens: GitHub PATs, Bearer tokens, and OpenAI-style sk-... keys.
• Crypto Keys: Full redaction of PEM-encoded Private Key blocks.
• Assignment-style Secrets: Automatic scrubbing of password: ..., secret=..., and api_key: ... patterns.

• Trusted: Your local machine, your repository, your configured Git remote.
• Untrusted / Variable: User input (CLI arguments), third-party AI agents, and external scripts interacting with the repo.

Security scanners (e.g., socket.dev) may flag these patterns:

Security fixes are applied to the latest release only.