Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/lweiss01/holistic

Your agents switch. Your repo remembers. Holistic gives your repo durable cross-agent memory for handoffs, history, next steps, and regressions.
https://github.com/lweiss01/holistic

agent-memory ai ai-agents automation context-management cross-agent cross-device cross-platform developer-tools handoff knowledge-management productivity project-memory

Last synced: 2 months ago
JSON representation

Your agents switch. Your repo remembers. Holistic gives your repo durable cross-agent memory for handoffs, history, next steps, and regressions.

Awesome Lists containing this project

README 

          
# Holistic



```

██╗  ██╗ ██████╗ ██╗     ██╗███████╗████████╗██╗ ██████╗

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

███████║██║   ██║██║     ██║███████╗   ██║   ██║██║     

██╔══██║██║   ██║██║     ██║╚════██║   ██║   ██║██║     

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

╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝╚══════╝   ╚═╝   ╚═╝ ╚═════╝



Your repo remembers, so your next agent doesn't have to guess.

Shared memory for AI agents, built into your repo.

```



[![npm version](https://img.shields.io/npm/v/holistic.svg)](https://www.npmjs.com/package/holistic)

[![Tests](https://img.shields.io/github/actions/workflow/status/lweiss01/holistic/test.yml?branch=main&label=tests)](https://github.com/lweiss01/holistic/actions)

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)

[![Node.js](https://img.shields.io/badge/node-%3E%3D24-339933.svg)](./package.json)



### 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](./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+.



```bash

npm install -g holistic

holistic bootstrap --yes

```



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



```text

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](#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:



```bash

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 🧭



```text

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**.



- **Read-Only by Default** — routine commands warn instead of mutating  

- **Explicit Consent** — system changes require `bootstrap` or `repair`  

- **Granular Control** — apply only what you want (`--yes-*` flags)  

- **Privacy Mode** — sync disabled by default with enforced guards  

- **MCP Logging Controls** — configurable visibility  

- **Redaction** — JWTs, tokens, AWS keys, and PEM blocks scrubbed  

- **Containment** — Enforced repository boundaries for all output paths (M009)  

- **Integrity** — Corrupt state files are preserved, not discarded, for auditability (M009)  

- **Safe Mode** — Minimal instruction mode for privacy-conscious environments (M009)  

- **Traceable Activity** — logs written locally  

- **Git-native behavior** — respects `.gitignore`  



For full details, see [SECURITY.md](./SECURITY.md).



---



## Quick start 🚀



### Install 📦



Requires Node.js 24+.



```bash

npm install -g holistic

```



Then verify the CLI is available:



```bash

holistic --help

```



For contributors or local source installs:



```bash

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:



```bash

npm install

npm link

```



### Set up a repo 🛠️



```bash

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:



```bash

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:



```bash

# 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:



```bash

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 `

- macOS/Linux: `./.holistic/system/holistic `



---



## Regression protection 🛡️



When an agent fixes something delicate, lock it in:



```bash

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 🗂️



```text

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 checks and configuration diagnostics **(Read-only)** |

| `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` | Runs the thin MCP server **(Read-only)** |

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



```bash

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:



```bash

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.



```json

{

  "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](https://github.com/lweiss01/holistic/issues). Early adopter feedback directly shapes the direction of the project.



For support and troubleshooting, see [SUPPORT.md](./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](./SECURITY.md).



---



## Quick links



- [Walkthrough](./docs/handoff-walkthrough.md)

- [Security & Privacy](./SECURITY.md)

- [Changelog](./CHANGELOG.md)

- [Contributing](./CONTRIBUTING.md)

- [License](./LICENSE)



---



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