{"id":47636108,"url":"https://github.com/lweiss01/holistic","last_synced_at":"2026-04-12T05:03:48.597Z","repository":{"id":345609299,"uuid":"1186583697","full_name":"lweiss01/holistic","owner":"lweiss01","description":"Your agents switch. Your repo remembers. Holistic gives your repo durable cross-agent memory for handoffs, history, next steps, and regressions.","archived":false,"fork":false,"pushed_at":"2026-03-28T20:31:17.000Z","size":1605,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-28T20:39:53.066Z","etag":null,"topics":["agent-memory","ai","ai-agents","automation","context-management","cross-agent","cross-device","cross-platform","developer-tools","handoff","knowledge-management","productivity","project-memory"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lweiss01.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap/00-code-hardening.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-19T19:27:38.000Z","updated_at":"2026-03-28T20:31:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lweiss01/holistic","commit_stats":null,"previous_names":["lweiss01/holistic"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/lweiss01/holistic","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lweiss01%2Fholistic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lweiss01%2Fholistic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lweiss01%2Fholistic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lweiss01%2Fholistic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lweiss01","download_url":"https://codeload.github.com/lweiss01/holistic/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lweiss01%2Fholistic/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31123510,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-28T20:32:38.821Z","status":"ssl_error","status_checked_at":"2026-03-28T20:24:19.814Z","response_time":79,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","ai","ai-agents","automation","context-management","cross-agent","cross-device","cross-platform","developer-tools","handoff","knowledge-management","productivity","project-memory"],"created_at":"2026-04-02T00:06:35.149Z","updated_at":"2026-04-12T05:03:48.583Z","avatar_url":"https://github.com/lweiss01.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Holistic\n\n```\n██╗  ██╗ ██████╗ ██╗     ██╗███████╗████████╗██╗ ██████╗\n██║  ██║██╔═══██╗██║     ██║██╔════╝╚══██╔══╝██║██╔════╝\n███████║██║   ██║██║     ██║███████╗   ██║   ██║██║     \n██╔══██║██║   ██║██║     ██║╚════██║   ██║   ██║██║     \n██║  ██║╚██████╔╝███████╗██║███████║   ██║   ██║╚██████╗\n╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝╚══════╝   ╚═╝   ╚═╝ ╚═════╝\n\nYour repo remembers, so your next agent doesn't have to guess.\nShared memory for AI agents, built into your repo.\n```\n\n[![npm version](https://img.shields.io/npm/v/holistic.svg)](https://www.npmjs.com/package/holistic)\n[![Tests](https://img.shields.io/github/actions/workflow/status/lweiss01/holistic/test.yml?branch=main\u0026label=tests)](https://github.com/lweiss01/holistic/actions)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D24-339933.svg)](./package.json)\n\n### One command. Every agent. Zero re-explaining. ✨  \nNo context loss. No fragile handoffs.\n\nHolistic 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.\n\n---\n\n## Why trust Holistic? 🔒\n\nHolistic is designed to be **safe to install, inspectable, and predictable**.\n\n- 🛡️ **Security-hardened** — enforced repository containment and state integrity checks (v0.6.4+)\n- 🧪 70+ automated tests covering core flows and security boundaries\n- 🛠️ Actively maintained (frequent releases)\n\n\u003e See [SECURITY.md](./SECURITY.md) for full technical details.\n\n---\n\n## Get started in 30 seconds ⚡\n\nOpen your project repo in PowerShell, Terminal, Command Prompt, or whatever shell you normally use.\n\nRequires Node.js 24+.\n\n```bash\nnpm install -g holistic\nholistic bootstrap --yes\n```\n\nAfter that, open the repo in your agent app and use this startup prompt:\n\n```text\nBefore 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.\n```\n\nThat is enough to get the basic Holistic workflow working.\n\nIf you want the fuller install and setup details, jump to [Quick start](#quick-start-).\n\n---\n\n## The problem 😵\n\nIf you use more than one AI coding assistant, the workflow usually falls apart:\n\n- 🔁 You re-explain the project every session  \n- 🐞 Bugs come back because the next agent does not know what was already fixed  \n- 🧠 Progress gets lost when context windows end  \n- 💥 Agents undo each other because there is no durable handoff  \n- 🌫️ It is hard to tell what is actually done  \n\nHolistic fixes that by making the repo the source of truth.\n\n---\n\n## What it feels like with HOLISTIC 🌿\n\nRun one setup command on a machine:\n\n```bash\nholistic bootstrap\n```\n\nThen daily use is mostly:\n\n1. Open the repo in Codex, Claude, or another supported app  \n2. Start a fresh session  \n3. Ask the agent to read `AGENTS.md` and `HOLISTIC.md`  \n4. Let Holistic carry continuity through checkpoints, handoffs, and repo memory  \n\nMost days, you do not need to keep a terminal process open or manually re-brief the agent.\n\n---\n\n## How it works 🧭\n\n```text\nholistic bootstrap\n      -\u003e\nYou open a repo in your agent app\n      -\u003e\nThe agent reads HOLISTIC.md and AGENTS.md\n      -\u003e\n\"Here's where we left off. Here's what's next. Continue as planned, tweak the plan, or start something new?\"\n      -\u003e\nWork happens\n      -\u003e\nHolistic checkpoints and handoffs keep repo memory current\n      -\u003e\nThe next agent picks up without a long re-explanation\n```\n\n---\n\n## 🔒 Security \u0026 Trust Model\n\nHolistic is designed to be **transparent, audit-safe, and consent-first**.\n\n- **Read-Only by Default** — routine commands warn instead of mutating  \n- **Explicit Consent** — system changes require `bootstrap` or `repair`  \n- **Granular Control** — apply only what you want (`--yes-*` flags)  \n- **Privacy Mode** — sync disabled by default with enforced guards  \n- **MCP Logging Controls** — configurable visibility  \n- **Redaction** — JWTs, tokens, AWS keys, and PEM blocks scrubbed  \n- **Containment** — Enforced repository boundaries for all output paths (M009)  \n- **Integrity** — Corrupt state files are preserved, not discarded, for auditability (M009)  \n- **Safe Mode** — Minimal instruction mode for privacy-conscious environments (M009)  \n- **Traceable Activity** — logs written locally  \n- **Git-native behavior** — respects `.gitignore`  \n\nFor full details, see [SECURITY.md](./SECURITY.md).\n\n---\n\n## Quick start 🚀\n\n### Install 📦\n\nRequires Node.js 24+.\n\n```bash\nnpm install -g holistic\n```\n\nThen verify the CLI is available:\n\n```bash\nholistic --help\n```\n\nFor contributors or local source installs:\n\n```bash\ngit clone https://github.com/lweiss01/holistic.git\ncd holistic\nnpm install\nnpm run build\nnpm pack\nnpm install -g ./holistic-*.tgz\n```\n\nFor local development without a packaged tarball:\n\n```bash\nnpm install\nnpm link\n```\n\n### Set up a repo 🛠️\n\n```bash\ncd my-project\nholistic bootstrap --remote origin --yes\ngit add .gitattributes HOLISTIC.md AGENTS.md CLAUDE.md GEMINI.md\ngit add .holistic/config.json .holistic/state.json\ngit add .holistic/context/\ngit commit -m \"feat: add holistic\"\n```\n\nBy 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.\n\nAdvanced overrides:\n\n```bash\nholistic bootstrap --state-ref refs/holistic/state\nholistic bootstrap --state-branch holistic/state\nholistic bootstrap --portable\n```\n\nIf you want repo scaffolding without changing local desktop integrations or daemon startup on the current machine, you can use granular flags to be surgical:\n\n```bash\n# Only install Git hooks and managed attributes\nholistic bootstrap --yes-hooks --yes-attr\n```\n\n**What to commit:**\n- `.gitattributes` - Holistic-managed line-ending rules for portable files\n- `.holistic/config.json` - repo configuration\n- `.holistic/state.json` - current session state  \n- `.holistic/context/` - generated docs (history, regression watch, adapters)\n- `.holistic/sessions/` - session history files\n\n**What NOT to commit:**\n- `.holistic/system/` - machine-local helper scripts and wrappers with absolute paths (already in `.gitignore`)\n\nThe portable repo memory is meant to be committed and synced. Machine-local helper scripts are generated for each machine and stay local.\n\n\n---\n\n\n## Daily workflow 🔄\n\nOne-time machine setup:\n\n- Run `holistic bootstrap`.\n- 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.\n- To be surgical about what is applied, use granular flags like `--yes-hooks`, `--yes-daemon`, or `--yes-mcp`.\n\nNormal use:\n\n- Start a session in Codex, Claude, or another supported app.\n- Let the agent read the repo instructions and current handoff state.\n- Work normally.\n- Use explicit CLI commands only when you want to inspect state manually or force a checkpoint or handoff yourself.\n\nUseful manual commands:\n\n```bash\nholistic status\nholistic checkpoint --reason \"...\"\nholistic handoff\n```\n\nIf `holistic` is not on `PATH` in a given shell, every bootstrapped repo also has a repo-local fallback:\n\n- Windows: `.\\.holistic\\system\\holistic.cmd \u003ccommand\u003e`\n- macOS/Linux: `./.holistic/system/holistic \u003ccommand\u003e`\n\n\n---\n\n\n## Regression protection 🛡️\n\nWhen an agent fixes something delicate, lock it in:\n\n```bash\nholistic checkpoint \\\n  --fixed \"login redirect loop\" \\\n  --fix-files \"src/auth.ts\" \\\n  --fix-risk \"changing redirect logic will re-introduce this\"\n```\n\nFuture agents will see that warning in the repo docs before they touch the risky area again.\n\n\n---\n\n\n## Works with multiple agent apps 🤝\n\nHolistic is model-agnostic. It works through repo files first, and can expose a thin MCP server where supported.\n\n### Startup parity matrix\n\nUse this table to decide whether startup should be automatic (MCP/tooling hook) or manual (`/holistic` / `holistic_resume`).\n\n| App / Surface | Reads | MCP auto-start | Startup action |\n|---|---|---|---|\n| Claude Desktop / Cowork | `CLAUDE.md` and repo docs | ✅ Yes | Usually automatic after `holistic bootstrap`; if context is stale, run `holistic_resume` |\n| Codex | `AGENTS.md` and repo docs | ❌ No | Run `/holistic` (or repo-local `holistic resume --continue`) at conversation start |\n| Antigravity | `GEMINI.md` and repo docs | ❌ No | Run `/holistic` at conversation start |\n| Gemini | `GEMINI.md` and repo docs | ❌ No | Run `/holistic` at conversation start |\n| Cursor | `.cursorrules` and repo docs | ❌ No | Run `/holistic` at conversation start for deterministic recap |\n| GitHub Copilot | `.github/copilot-instructions.md` and repo docs | ❌ No | Run `/holistic` at conversation start |\n| Goose | `AGENTS.md` and repo docs | ❌ No | Run repo-local `holistic resume --continue` in the shell session |\n| GSD / GSD2 | `AGENTS.md` and repo docs | ❌ No | Run `/holistic` or `holistic_resume` before first implementation step |\n| Other VS Code forks | `AGENTS.md` and repo docs | ❌ No | Treat as manual-start and run `/holistic` |\n| Web tools | repo docs pasted manually | ❌ No | Manual copy/paste recap from Holistic docs |\n\n\n---\n\n\n## What lives in your repo 🗂️\n\n```text\nmy-project/\n|- HOLISTIC.md\n|- AGENTS.md\n|- CLAUDE.md\n|- GEMINI.md\n|- .cursorrules\n|- .windsurfrules\n|- .gitattributes\n|- .github/\n|  `- copilot-instructions.md\n`- .holistic/\n   |- config.json\n   |- state.json\n   |- sessions/\n   `- context/\n      |- project-history.md\n      |- regression-watch.md\n      `- adapters/\n```\n\nThe 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`).\n\n\n---\n\n\n## Commands\n\n| Command | Description |\n| :--- | :--- |\n| `holistic init` | Base repo setup and scaffolding |\n| `holistic bootstrap` | One-step machine setup. Required `--yes` for Core Setup, or granular `--yes-*` flags. |\n| `holistic doctor` | Health checks and configuration diagnostics **(Read-only)** |\n| `holistic repair` | Regenerates `.holistic/system/` local helpers |\n| `holistic resume / start` | Loads project recap and prints state **(Read-only)** |\n| `holistic start-new` | Starts a fresh session |\n| `holistic checkpoint` | Saves progress and context **(Stateful)** |\n| `holistic handoff` | Ends a session with a handoff message **(Stateful)** |\n| `holistic status` | Shows current state and sync activity **(Read-only)** |\n| `holistic diff` | Compares two session IDs **(Read-only)** |\n| `holistic search` | Finds and retrieves session state **(Read-only)** |\n| `holistic serve` | Runs the thin MCP server **(Read-only)** |\n| `holistic watch` | Foreground daemon; automatically creates checkpoints **(Mutating)** |\n\n### Slash command helper text (agent-facing)\n\nWhen your agent UI supports slash shortcuts, use these helper mappings:\n\n| Slash | Helper text | CLI equivalent |\n|---|---|---|\n| `/holistic` | Load repo recap and confirm: continue, tweak, or start new. | `holistic resume --continue` |\n| `/checkpoint` | Save a structured checkpoint at a natural breakpoint. | `holistic checkpoint --reason \"...\"` |\n| `/handoff` | Finalize session handoff with summary, next steps, blockers, and regression risks. | `holistic handoff` |\n\n\n```bash\nholistic handoff \\\n  --summary \"Implemented OAuth flow and token storage\" \\\n  --next \"Wire up the refresh token endpoint\" \\\n  --blocker \"Need refresh token endpoint from backend team\"\n```\n\n\n---\n\n\n## Architecture\n\nHolistic is intentionally repo-first, not machine-first.\n\n| Layer | Purpose | Portable? |\n|---|---|---|\n| Repo memory | Shared handoff, history, regression, and session state | Yes |\n| State ref | Cross-device distribution of Holistic state via git | Yes |\n| Local daemon | Passive capture on one machine | No |\n\nThat split is what makes Holistic work across tools and devices instead of only on one laptop.\n\n### MCP server mode\n\nHolistic can run as a thin MCP server for agent-native workflows:\n\n```bash\nholistic serve\n```\n\nIn normal use, Claude Desktop can launch this automatically after `holistic bootstrap` configures the MCP entry. You usually only run it manually for debugging.\n\nWhen 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.\n\n```json\n{\n  \"mcpServers\": {\n    \"holistic\": {\n      \"command\": \"holistic\",\n      \"args\": [\"serve\"],\n      \"env\": {\n        \"HOLISTIC_REPO\": \"/path/to/your/project\"\n      }\n    }\n  }\n}\n```\n\n\n---\n\n\n## Why this matters\n\nIf you are already using more than one AI coding assistant, you already have the continuity problem.\n\nHolistic gives you:\n\n- Less repeated explanation\n- Fewer accidental regressions\n- Clearer handoffs across apps and devices\n- A durable record of what changed and why\n- Agents that can get to work quickly\n\n\n---\n\n\n## Beta Feedback Welcome 🙏\n\nHolistic 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.\n\nFor support and troubleshooting, see [SUPPORT.md](./SUPPORT.md).\n\n\n---\n\n\nHolistic 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.\n\n### Trust Architecture:\n- **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.\n- **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).\n- **Surgical Control**: Use granular flags (`--yes-hooks`, `--yes-daemon`, `--yes-mcp`, `--yes-attr`, `--yes-claude`) to apply only the specific integrations you want.\n- **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.\n- **MCP Logging Privacy**: Control what Holistic reports to your agent UI. Set `mcpLogging` to `\"off\"`, `\"minimal\"` (default), or `\"default\"` in `.holistic/config.json`.\n- **Advanced Redaction**: Holistic automatically scrubs JWTs, Bearer tokens, AWS keys, and PEM blocks from all generated session metadata to prevent context leakage.\n- **Traceable Activity**: Background sync operations (PowerShell/Bash) are visible and logged with timestamps to `.holistic/system/sync.log`.\n- **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})$.\n\n### What it does:\n- Writes session state into `.holistic/` inside your repo (committed files you control)\n- Installs a daemon via standard OS autostart (Windows Startup folder, macOS LaunchAgents, Linux systemd user)\n- Can push Holistic state to a hidden git ref on your configured remote (opt-in, your repo only)\n\n### What it does NOT do:\n- Does not read or transmit file contents outside your repo\n- Does not access credentials or tokens\n- Does not phone home to any external service\n- Does not use obfuscated scripts or hidden windows\n\nFor the full technical disclosure, see [SECURITY.md](./SECURITY.md).\n\n\n---\n\n\n## Quick links\n\n- [Walkthrough](./docs/handoff-walkthrough.md)\n- [Security \u0026 Privacy](./SECURITY.md)\n- [Changelog](./CHANGELOG.md)\n- [Contributing](./CONTRIBUTING.md)\n- [License](./LICENSE)\n\n\n\n---\n\n\n\u003cp align=\"center\"\u003e\u003cem\u003eBuilt for people who use more than one AI assistant and are tired of paying the context tax.\u003c/em\u003e\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flweiss01%2Fholistic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flweiss01%2Fholistic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flweiss01%2Fholistic/lists"}