holistic 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.2.0 - 2026-03-21
+
+First public npm-ready release of Holistic.
+
+- Added a one-step `holistic bootstrap` flow for repo setup plus optional local machine integration.
+- Added thin MCP server support with `holistic serve`.
+- Added `holistic status` and `holistic diff`.
+- Added portable hook installation plus self-healing Holistic-managed hook refresh.
+- Added hidden-ref portable state sync via `refs/holistic/state` to avoid GitHub branch noise.
+- Added managed `.gitattributes` generation for portable Holistic files.
+- Added packaging and install smoke validation for clean-repo bootstrap.

package/CONTRIBUTING.md

@@ -0,0 +1,121 @@
+# Contributing to Holistic
+
+Holistic is trying to solve a very specific pain: project work gets fragmented across agents, apps, devices, and half-finished sessions. Contributions are most helpful when they make handoffs clearer, memory more durable, or regressions harder to repeat.
+
+## What we care about
+
+- preserving project context across agent switches
+- reducing repeated regressions
+- making setup simple enough that people will actually use it
+- keeping the repo-first model portable across tools and devices
+- making long-term project history useful, not noisy
+
+## Local development
+
+Requirements:
+
+- Node.js 24+
+- Git
+
+Install and verify:
+
+```bash
+npm install
+node --version
+npm test
+```
+
+## Project structure
+
+| Path | Purpose |
+| --- | --- |
+| `src/cli.ts` | public CLI entrypoint |
+| `src/daemon.ts` | passive background capture |
+| `src/core/state.ts` | canonical state model and session lifecycle |
+| `src/core/docs.ts` | generated repo-visible memory docs |
+| `src/core/setup.ts` | repo init and system helper generation |
+| `tests/run-tests.ts` | end-to-end regression harness |
+| `.holistic-local/` | ignored local Holistic runtime for this public product repo |
+
+## Dogfooding Holistic in this repo
+
+This public product repo is a special case.
+
+Holistic dogfooding here must stay local-only and untracked. The repo-level override redirects runtime state into `.holistic-local/`, `HOLISTIC.local.md`, and `AGENTS.local.md` instead of tracked public runtime files.
+
+Recommended local setup for working on Holistic itself:
+
+```bash
+node --experimental-strip-types src/cli.ts bootstrap --install-daemon false --configure-mcp false --install-hooks false
+```
+
+Common local flows:
+
+```bash
+node --experimental-strip-types src/cli.ts resume --agent codex
+node --experimental-strip-types src/cli.ts checkpoint --reason "milestone"
+node --experimental-strip-types src/cli.ts handoff
+```
+
+Do not initialize tracked `.holistic/` runtime state in this repo, and do not use a visible `holistic/state` branch here for self-dogfooding.
+
+For normal user repos, tracked `.holistic/` runtime plus the hidden portable state ref (`refs/holistic/state`) is the standard path. This product repo itself should stay public, clean, and main-only.
+
+## Contribution guidelines
+
+### 1. Prefer repo-first solutions
+
+If a feature only works on one machine or in one app, it is probably not enough on its own. Holistic should degrade gracefully to repo-visible memory.
+
+### 2. Preserve long-term memory
+
+New features should help answer:
+
+- what changed
+- why it changed
+- what impact it had
+- what should not regress later
+
+### 3. Avoid transcript bloat
+
+Holistic should preserve durable, useful state. It should not turn into a raw log dump of every prompt and response.
+
+### 4. Protect user trust
+
+- redact secrets
+- do not commit sensitive local state by accident
+- make automated behavior legible and reviewable
+
+### 5. Test behavior, not just helpers
+
+When possible, add tests around the user-visible workflow:
+
+- resume
+- checkpoint
+- handoff
+- carryover to a new session
+- regression preservation
+- cross-device sync behavior
+
+## Pull request checklist
+
+Before opening a PR:
+
+- run `npm test`
+- run `npm run build`
+- verify the README and docs still match the behavior
+- think through whether your change improves or harms cross-agent portability
+- call out any new risks around regression memory, secrecy, or sync
+
+## Good areas for contributions
+
+- stronger regression tracking
+- better cross-device sync ergonomics
+- richer handoff review flows
+- app-specific integrations that still honor the repo-first contract
+- clearer history summarization
+- safer passive capture
+
+## Design principle
+
+Holistic should help the next agent act like they were there the whole time.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lisa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,329 @@
+# 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.
+
+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.
+
+## Public repo hygiene
+
+The Holistic product repo is a special case when it dogfoods itself.
+
+Normal user repos may commit portable Holistic runtime files and sync them through a dedicated portable git ref. This public repo should not ship a contributor's personal session history, handoff state, or live dogfooding runtime files. Self-dogfooding on this repo is redirected to ignored local files instead.
+
+---
+
+## 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 now
+
+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 run `npm start`, keep a terminal process open, or manually re-brief the agent.
+
+`holistic bootstrap` is a machine setup command, not just a repo setup command. By default it can install local startup helpers and configure Claude Desktop MCP on that machine.
+
+---
+
+## 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
+```
+
+---
+
+## 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
+git add .gitattributes HOLISTIC.md AGENTS.md CLAUDE.md GEMINI.md HISTORY.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.
+
+Advanced overrides:
+
+```bash
+holistic bootstrap --state-ref refs/holistic/state
+holistic bootstrap --state-branch holistic/state
+```
+
+If you want repo scaffolding without changing local desktop integrations or daemon startup on the current machine, use:
+
+```bash
+holistic bootstrap --install-daemon false --configure-mcp false
+```
+
+**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/*.sh` and `.holistic/system/*.ps1` - machine-local scripts 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.
+
+After that, open the repo in your agent app and use a startup prompt like:
+
+```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 for normal repo-first continuity.
+
+---
+
+## 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.
+- If you only want repo files and hooks, use `holistic bootstrap --install-daemon false --configure-mcp false`.
+
+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
+```
+
+---
+
+## 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 also expose a thin MCP server where supported.
+
+| App | Reads | Startup experience |
+|---|---|---|
+| Claude Desktop | `CLAUDE.md` and repo docs | automatic plus MCP support |
+| Codex | `AGENTS.md` and repo docs | automatic |
+| Gemini / Antigravity | `GEMINI.md` and repo docs | automatic |
+| Other VS Code forks | `AGENTS.md` and repo docs | usually automatic |
+| Web tools | repo docs pasted manually | manual |
+
+---
+
+## What lives in your repo
+
+```text
+my-project/
+|- HOLISTIC.md
+|- AGENTS.md
+|- CLAUDE.md
+|- GEMINI.md
+|- HISTORY.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 under `.holistic/system/` are generated for each machine and stay local (already in `.gitignore`).
+
+---
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `holistic init` | Base repo setup and scaffolding |
+| `holistic bootstrap` | One-step machine setup for repo files, hooks, and by-default local daemon/MCP integration setup |
+| `holistic start --agent <name>` | Opens a session and prints the ASCII banner plus recap |
+| `holistic checkpoint --reason "..."` | Saves progress and context |
+| `holistic handoff` | Ends a session with a handoff |
+| `holistic status` | Shows the current state |
+| `holistic diff --from <id> --to <id>` | Compares two sessions |
+| `holistic serve` | Runs the thin MCP server and prints a startup banner to `stderr` |
+| `holistic watch` | Foreground daemon mode for automatic checkpoints |
+
+### Non-interactive 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
+
+---
+
+## Quick links
+
+- [Walkthrough](./docs/handoff-walkthrough.md)
+- [Changelog](./CHANGELOG.md)
+- [Contributing](./CONTRIBUTING.md)
+- [License](./LICENSE)
+
+---
+
+<p align="center"><em>Built for people who use more than one AI assistant and are tired of paying the context tax.</em></p>

package/bin/holistic

@@ -0,0 +1,17 @@
+#!/usr/bin/env sh
+SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
+node --experimental-strip-types "$SCRIPT_DIR/../src/cli.ts" "$@"
+status=$?
+if [ "$status" -ne 0 ]; then
+  exit "$status"
+fi
+if [ "$1" = "handoff" ] && [ -f "$PWD/.holistic/context/pending-commit.txt" ]; then
+  message=$(head -n 1 "$PWD/.holistic/context/pending-commit.txt")
+  if [ -n "$message" ]; then
+    git add -- HOLISTIC.md AGENTS.md .holistic && git commit -m "$message"
+    if [ "$?" -eq 0 ] && [ -f "$PWD/.holistic/system/sync-state.sh" ]; then
+      /bin/sh "$PWD/.holistic/system/sync-state.sh" || true
+      node --experimental-strip-types "$SCRIPT_DIR/../src/cli.ts" internal-mark-commit --message "$message"
+    fi
+  fi
+fi

package/bin/holistic.cmd

@@ -0,0 +1,23 @@
+@echo off
+setlocal
+set SCRIPT_DIR=%~dp0
+node --experimental-strip-types "%SCRIPT_DIR%..\src\cli.ts" %*
+if errorlevel 1 exit /b %errorlevel%
+if /I "%~1"=="handoff" (
+  set PENDING_FILE=%CD%\.holistic\context\pending-commit.txt
+  if exist "%PENDING_FILE%" (
+    set /p COMMIT_MSG=<"%PENDING_FILE%"
+    if defined COMMIT_MSG (
+      git add -- HOLISTIC.md AGENTS.md .holistic
+      if not errorlevel 1 (
+        git commit -m "%COMMIT_MSG%"
+        if not errorlevel 1 (
+          if exist "%CD%\.holistic\system\sync-state.ps1" (
+            powershell -NoProfile -ExecutionPolicy Bypass -File "%CD%\.holistic\system\sync-state.ps1"
+          )
+          node --experimental-strip-types "%SCRIPT_DIR%..\src\cli.ts" internal-mark-commit --message "%COMMIT_MSG%"
+        )
+      )
+    )
+  )
+)

package/bin/holistic.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import fs from "node:fs";
+import path from "node:path";
+
+const currentFile = fileURLToPath(import.meta.url);
+const repoRoot = path.resolve(path.dirname(currentFile), "..");
+const cliPath = path.resolve(repoRoot, "dist/cli.js");
+const args = process.argv.slice(2);
+const result = spawnSync(process.execPath, [cliPath, ...args], {
+  stdio: "inherit",
+  cwd: process.cwd(),
+});
+
+if (result.status !== 0) {
+  process.exit(result.status ?? 1);
+}
+
+if (args[0] === "handoff") {
+  const pendingCommitPath = path.join(process.cwd(), ".holistic", "context", "pending-commit.txt");
+  if (fs.existsSync(pendingCommitPath)) {
+    const message = fs.readFileSync(pendingCommitPath, "utf8").split(/\r?\n/)[0]?.trim();
+    if (message) {
+      const addResult = spawnSync("git", ["add", "--", "HOLISTIC.md", "AGENTS.md", ".holistic"], {
+        stdio: "inherit",
+        cwd: process.cwd(),
+      });
+      if ((addResult.status ?? 1) === 0) {
+        const commitResult = spawnSync("git", ["commit", "-m", message], {
+          stdio: "inherit",
+          cwd: process.cwd(),
+        });
+        if ((commitResult.status ?? 1) === 0) {
+          const syncScript = path.join(process.cwd(), ".holistic", "system", process.platform === "win32" ? "sync-state.ps1" : "sync-state.sh");
+          if (fs.existsSync(syncScript)) {
+            if (process.platform === "win32") {
+              spawnSync("powershell", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", syncScript], {
+                stdio: "inherit",
+                cwd: process.cwd(),
+              });
+            } else {
+              spawnSync("/bin/sh", [syncScript], {
+                stdio: "inherit",
+                cwd: process.cwd(),
+              });
+            }
+          }
+          spawnSync(process.execPath, [cliPath, "internal-mark-commit", "--message", message], {
+            stdio: "inherit",
+            cwd: process.cwd(),
+          });
+        }
+      }
+    }
+  }
+}
+
+process.exit(0);

package/dist/__tests__/mcp-notification.test.d.ts

@@ -0,0 +1,5 @@
+export declare const tests: {
+    name: string;
+    run: () => void;
+}[];
+//# sourceMappingURL=mcp-notification.test.d.ts.map

package/dist/__tests__/mcp-notification.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-notification.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/mcp-notification.test.ts"],"names":[],"mappings":"AA4CA,eAAO,MAAM,KAAK;;;GAgOjB,CAAC"}