Holistic

██╗  ██╗ ██████╗ ██╗     ██╗███████╗████████╗██╗ ██████╗
██║  ██║██╔═══██╗██║     ██║██╔════╝╚══██╔══╝██║██╔════╝
███████║██║   ██║██║     ██║███████╗   ██║   ██║██║     
██╔══██║██║   ██║██║     ██║╚════██║   ██║   ██║██║     
██║  ██║╚██████╔╝███████╗██║███████║   ██║   ██║╚██████╗
╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝╚══════╝   ╚═╝   ╚═╝ ╚═════╝

Your repo remembers, so your next agent doesn't have to guess.
Shared memory for AI agents, built into your repo.

One command. Every agent. Zero re-explaining. ✨

No context loss. No fragile handoffs.

Holistic gives your AI agents shared memory inside the repo itself. When you switch from Claude to Codex to Gemini, the next agent can see what happened last time, what not to break, and what should happen next.

---

Why trust Holistic? 🔒

Holistic is designed to be safe to install, inspectable, and predictable.

• 🛡️ Security-hardened — enforced repository containment and state integrity checks (v0.6.4+)
• 🧪 70+ automated tests covering core flows and security boundaries
• 🛠️ Actively maintained (frequent releases)

See SECURITY.md for full technical details.

---

Get started in 30 seconds ⚡

Open your project repo in PowerShell, Terminal, Command Prompt, or whatever shell you normally use.

Requires Node.js 24+.

npm install -g holistic
holistic bootstrap --yes

After that, open the repo in your agent app and use this startup prompt:

Before doing any other work, read AGENTS.md and HOLISTIC.md, recap the current state briefly, and ask me exactly one question: continue as planned, tweak the plan, or start something new.

That is enough to get the basic Holistic workflow working.

If you want the fuller install and setup details, jump to Quick start.

---

The problem 😵

If you use more than one AI coding assistant, the workflow usually falls apart:

• 🔁 You re-explain the project every session
• 🐞 Bugs come back because the next agent does not know what was already fixed
• 🧠 Progress gets lost when context windows end
• 💥 Agents undo each other because there is no durable handoff
• 🌫️ It is hard to tell what is actually done

Holistic fixes that by making the repo the source of truth.

---

What it feels like with HOLISTIC 🌿

Run one setup command on a machine:

holistic bootstrap

Then daily use is mostly:

1. Open the repo in Codex, Claude, or another supported app
2. Start a fresh session
3. Ask the agent to read AGENTS.md and HOLISTIC.md
4. Let Holistic carry continuity through checkpoints, handoffs, and repo memory

Most days, you do not need to keep a terminal process open or manually re-brief the agent.

---

How it works 🧭

holistic bootstrap
      ->
You open a repo in your agent app
      ->
The agent reads HOLISTIC.md and AGENTS.md
      ->
"Here's where we left off. Here's what's next. Continue as planned, tweak the plan, or start something new?"
      ->
Work happens
      ->
Holistic checkpoints and handoffs keep repo memory current
      ->
The next agent picks up without a long re-explanation

---

🔒 Security & Trust Model

Holistic is designed to be transparent, audit-safe, and consent-first.

The current version of Holistic (v0.6.5) includes:

• Repository Path Containment: Enforced boundaries for all repo-configured output paths.
• State Integrity Protection: Corrupted state.json files are preserved as .corrupt-*.json and surfaced as a Degraded Mode diagnostic instead of being silently lost.
• Safe Mode: A minimal-instruction mode for privacy-conscious or highly-constrained environments.
• Non-Mutating Build: The build pipeline now stages sources, ensuring src/ remains immutable.
• Read-Only MCP Server: The server startup and client connection routines are strictly non-mutating (warning-only staleness checks).

For full details, see SECURITY.md.

---

Quick start 🚀

Install 📦

Requires Node.js 24+.

npm install -g holistic

Then verify the CLI is available:

holistic --help

For contributors or local source installs:

git clone https://github.com/lweiss01/holistic.git
cd holistic
npm install
npm run build
npm pack
npm install -g ./holistic-*.tgz

For local development without a packaged tarball:

npm install
npm link

Set up a repo 🛠️

cd my-project
holistic bootstrap --remote origin --yes
git add .gitattributes HOLISTIC.md AGENTS.md CLAUDE.md GEMINI.md
git add .holistic/config.json .holistic/state.json
git add .holistic/context/
git commit -m "feat: add holistic"

By default, Holistic now syncs portable state through a hidden git ref (refs/holistic/state) to avoid GitHub branch noise. That sync mirrors Holistic state only - it does not auto-push your working branch.

Advanced overrides:

holistic bootstrap --state-ref refs/holistic/state
holistic bootstrap --state-branch holistic/state
holistic bootstrap --portable

If you want repo scaffolding without changing local desktop integrations or daemon startup on the current machine, you can use granular flags to be surgical:

# Only install Git hooks and managed attributes
holistic bootstrap --yes-hooks --yes-attr

What to commit:

• .gitattributes - Holistic-managed line-ending rules for portable files
• .holistic/config.json - repo configuration
• .holistic/state.json - current session state
• .holistic/context/ - generated docs (history, regression watch, adapters)
• .holistic/sessions/ - session history files

What NOT to commit:

• .holistic/system/ - machine-local helper scripts and wrappers with absolute paths (already in .gitignore)

The portable repo memory is meant to be committed and synced. Machine-local helper scripts are generated for each machine and stay local.

---

Daily workflow 🔄

One-time machine setup:

• Run holistic bootstrap.
• By default it scaffolds repo files, installs hooks, sets up daemon startup, and configures supported integrations such as Claude Desktop MCP on the current machine.
• To be surgical about what is applied, use granular flags like --yes-hooks, --yes-daemon, or --yes-mcp.

Normal use:

• Start a session in Codex, Claude, or another supported app.
• Let the agent read the repo instructions and current handoff state.
• Work normally.
• Use explicit CLI commands only when you want to inspect state manually or force a checkpoint or handoff yourself.

Useful manual commands:

holistic status
holistic checkpoint --reason "..."
holistic handoff

If holistic is not on PATH in a given shell, every bootstrapped repo also has a repo-local fallback:

• Windows: .\.holistic\system\holistic.cmd <command>
• macOS/Linux: ./.holistic/system/holistic <command>

---

Regression protection 🛡️

When an agent fixes something delicate, lock it in:

holistic checkpoint \
  --fixed "login redirect loop" \
  --fix-files "src/auth.ts" \
  --fix-risk "changing redirect logic will re-introduce this"

Future agents will see that warning in the repo docs before they touch the risky area again.

---

Works with multiple agent apps 🤝

Holistic is model-agnostic. It works through repo files first, and can expose a thin MCP server where supported.

Startup parity matrix

Use this table to decide whether startup should be automatic (MCP/tooling hook) or manual (/holistic / holistic_resume).

App / Surface	Reads	MCP auto-start	Startup action
Claude Desktop / Cowork	CLAUDE.md and repo docs	✅ Yes	Usually automatic after holistic bootstrap; if context is stale, run holistic_resume
Codex	AGENTS.md and repo docs	❌ No	Run /holistic (or repo-local holistic resume --continue) at conversation start
Antigravity	GEMINI.md and repo docs	❌ No	Run /holistic at conversation start
Gemini	GEMINI.md and repo docs	❌ No	Run /holistic at conversation start
Cursor	.cursorrules and repo docs	❌ No	Run /holistic at conversation start for deterministic recap
GitHub Copilot	.github/copilot-instructions.md and repo docs	❌ No	Run /holistic at conversation start
Goose	AGENTS.md and repo docs	❌ No	Run repo-local holistic resume --continue in the shell session
GSD / GSD2	AGENTS.md and repo docs	❌ No	Run /holistic or holistic_resume before first implementation step
Other VS Code forks	AGENTS.md and repo docs	❌ No	Treat as manual-start and run /holistic
Web tools	repo docs pasted manually	❌ No	Manual copy/paste recap from Holistic docs

---

What lives in your repo 🗂️

my-project/
|- HOLISTIC.md
|- AGENTS.md
|- CLAUDE.md
|- GEMINI.md
|- .cursorrules
|- .windsurfrules
|- .gitattributes
|- .github/
|  `- copilot-instructions.md
`- .holistic/
   |- config.json
   |- state.json
   |- sessions/
   `- context/
      |- project-history.md
      |- regression-watch.md
      `- adapters/

The portable repo memory (config, state, context, sessions) is meant to be committed and synced. Machine-local helper scripts and repo-local CLI fallbacks under .holistic/system/ are generated for each machine and stay local (already in .gitignore).

---

Commands

Command	Description
holistic init	Base repo setup and scaffolding
holistic bootstrap	One-step machine setup. Required --yes for Core Setup, or granular --yes-* flags.
holistic doctor	Health check & config diagnostics (supports --json)
holistic repair	Regenerates .holistic/system/ local helpers
holistic resume / start	Loads project recap and prints state (Read-only)
holistic start-new	Starts a fresh session
holistic checkpoint	Saves progress and context (Stateful)
holistic handoff	Ends a session with a handoff message (Stateful)
holistic status	Shows current state and sync activity (Read-only)
holistic diff	Compares two session IDs (Read-only)
holistic search	Finds and retrieves session state (Read-only)
holistic serve	Strictly read-only MCP server (stdio)
holistic watch	Foreground daemon; automatically creates checkpoints (Mutating)

Slash command helper text (agent-facing)

When your agent UI supports slash shortcuts, use these helper mappings:

Slash	Helper text	CLI equivalent
/holistic	Load repo recap and confirm: continue, tweak, or start new.	holistic resume --continue
/checkpoint	Save a structured checkpoint at a natural breakpoint.	holistic checkpoint --reason "..."
/handoff	Finalize session handoff with summary, next steps, blockers, and regression risks.	holistic handoff

holistic handoff \
  --summary "Implemented OAuth flow and token storage" \
  --next "Wire up the refresh token endpoint" \
  --blocker "Need refresh token endpoint from backend team"

---

Architecture

Holistic is intentionally repo-first, not machine-first.

Layer	Purpose	Portable?
Repo memory	Shared handoff, history, regression, and session state	Yes
State ref	Cross-device distribution of Holistic state via git	Yes
Local daemon	Passive capture on one machine	No

That split is what makes Holistic work across tools and devices instead of only on one laptop.

MCP server mode

Holistic can run as a thin MCP server for agent-native workflows:

holistic serve

In normal use, Claude Desktop can launch this automatically after holistic bootstrap configures the MCP entry. You usually only run it manually for debugging.

When you do run holistic serve manually in a terminal, Holistic prints its ASCII startup banner to stderr so you get visible confirmation without corrupting the MCP stdout transport.

{
  "mcpServers": {
    "holistic": {
      "command": "holistic",
      "args": ["serve"],
      "env": {
        "HOLISTIC_REPO": "/path/to/your/project"
      }
    }
  }
}

---

Why this matters

If you are already using more than one AI coding assistant, you already have the continuity problem.

Holistic gives you:

• Less repeated explanation
• Fewer accidental regressions
• Clearer handoffs across apps and devices
• A durable record of what changed and why
• Agents that can get to work quickly

---

Beta Feedback Welcome 🙏

Holistic is in early beta. If you hit rough edges, unexpected behavior, or have ideas for improvement, please open an issue. Early adopter feedback directly shapes the direction of the project.

For support and troubleshooting, see SUPPORT.md.

---

Holistic is designed to be transparent, audit-safe, and consent-first. It is a shared memory layer that stays in your repo, not a cloud service that watches your screen.

Trust Architecture:

• Read-Only by Default: Routine commands (status, resume, diff) are strictly non-mutating. They will only warn you if git hooks are missing or outdated, rather than fixing them silently.
• Granular Consent: holistic bootstrap uses a "Consent-First" model. It displays a summary of system-modifying actions and requires an explicit --yes for the Core Setup (hooks, daemon, MCP, attributes).
• Surgical Control: Use granular flags (--yes-hooks, --yes-daemon, --yes-mcp, --yes-attr, --yes-claude) to apply only the specific integrations you want.
• Privacy Mode Enforcement: When portableState is disabled (the default), all generated sync scripts and git hooks contain early-exit guards to prevent any accidental remote traffic.
• MCP Logging Privacy: Control what Holistic reports to your agent UI. Set mcpLogging to "off", "minimal" (default), or "default" in .holistic/config.json.
• Advanced Redaction: Holistic automatically scrubs JWTs, Bearer tokens, AWS keys, and PEM blocks from all generated session metadata to prevent context leakage.
• Traceable Activity: Background sync operations (PowerShell/Bash) are visible and logged with timestamps to .holistic/system/sync.log.
• Git-Native Snapshotting: The repo snapshot logic uses native git ls-files, ensuring that your .gitignore rules are perfectly respected and performance stays $O(\text{repo size})$.

What it does:

• Writes session state into .holistic/ inside your repo (committed files you control)
• Installs a daemon via standard OS autostart (Windows Startup folder, macOS LaunchAgents, Linux systemd user)
• Can push Holistic state to a hidden git ref on your configured remote (opt-in, your repo only)

What it does NOT do:

• Does not read or transmit file contents outside your repo
• Does not access credentials or tokens
• Does not phone home to any external service
• Does not use obfuscated scripts or hidden windows

For the full technical disclosure, see SECURITY.md.

---

Quick links

• Walkthrough
• Security & Privacy
• Changelog
• Contributing
• License

---

Built for people who use more than one AI assistant and are tired of paying the context tax.