claude-compass 0.0.1

package/claude-compass-spec.md

@@ -0,0 +1,217 @@
+claude-memory — Full Product Spec
+What It Is
+claude-memory is an npm package that extends Claude Code with automatic CLAUDE.md lifecycle management. It installs hooks and agents into Claude Code's existing infrastructure so that project context stays accurate over time — silently, without interrupting the developer's workflow.
+It works exclusively with Claude Code. No separate runtime, no background processes, no cloud dependency.
+
+How It Works — The Full Flow
+Developer works in Claude Code
+         ↓
+PostToolUse hook fires after significant file writes
+         ↓
+Hook appends one-line note to .claude/pending-updates.md
+(pure bash, zero LLM tokens)
+         ↓
+Session ends
+         ↓
+SessionEnd hook prints summary:
+"✦ claude-memory: 3 changes logged"
+         ↓
+Developer finishes their day or a feature
+         ↓
+claude-md-updater agent runs (manually or on threshold)
+         ↓
+Reads pending-updates.md + CLAUDE.md
+Makes surgical updates to CLAUDE.md
+Clears pending-updates.md
+Prints: "CLAUDE.md updated — 2 conventions added, 1 gotcha recorded"
+
+npm Package Structure
+claude-memory/
+├── package.json
+├── bin/
+│   └── claude-memory.js      ← CLI entry point
+├── src/
+│   ├── install.js             ← installs hooks + agents into ~/.claude
+│   ├── status.js              ← reads and displays current state
+│   ├── update.js              ← manually triggers claude-md-updater
+│   └── init.js                ← creates CLAUDE.md + folder structure
+├── templates/
+│   ├── hooks/
+│   │   ├── post-tool-use.js   ← the hook that logs changes
+│   │   └── session-end.js     ← the hook that prints summary
+│   └── agents/
+│       └── claude-md-updater.md  ← the updater agent
+└── README.md
+
+Installation Experience
+User runs:
+bashnpm install -g claude-memory
+claude-memory init
+claude-memory init does the following in order:
+
+Detects if the current directory is a git repo — if not, warns but continues
+Checks if CLAUDE.md already exists — if yes, backs it up to CLAUDE.md.backup before touching anything
+Creates .claude/context/ directory
+Creates .claude/pending-updates.md with empty state
+Installs hooks into ~/.claude/hooks/ (global) or .claude/hooks/ (project)
+Installs claude-md-updater agent into .claude/agents/
+If no CLAUDE.md exists, runs codebase-explorer agent to generate one
+Prints:
+
+✦ claude-memory initialized
+
+  CLAUDE.md          ✓ ready
+  pending-updates    ✓ ready
+  hooks              ✓ post-tool-use, session-end registered
+  agent              ✓ claude-md-updater installed
+
+  Changes will be logged silently during sessions.
+  Run: claude-memory status  to check anytime.
+
+File Architecture
+CLAUDE.md — stable core
+Only contains things that rarely change:
+
+Project purpose (1-2 sentences)
+Tech stack
+Key architectural decisions
+Coding conventions
+Folder structure overview
+Critical gotchas
+A ## Last Updated line at the bottom with date
+
+.claude/pending-updates.md
+Append-only log during sessions. Format:
+[2026-04-03 14:23] FILE_WRITE: server/routes/auth.js — new OAuth route added
+[2026-04-03 14:31] FILE_WRITE: server/db/migrations/004_add_sessions.sql — new sessions table
+[2026-04-03 15:12] AGENT_NOTE: discovered that session tokens must be rotated on each request
+Gets cleared after each successful CLAUDE.md update.
+.claude/context/ — optional reference files
+Only created if needed. Never auto-loaded — agents read them explicitly when relevant:
+.claude/context/
+├── decisions.md       ← architectural decisions and why
+├── known-issues.md    ← current bugs and gotchas
+└── recent-changes.md  ← what changed in last 2 weeks
+
+Hook Design
+PostToolUse Hook — post-tool-use.js
+Fires after every tool use in Claude Code.
+Logic:
+
+If tool is NOT a file write (Write, Edit, MultiEdit) → exit immediately, do nothing
+If file written is in node_modules/, .git/, dist/, build/ → exit, do nothing
+If file written is a lockfile (package-lock.json, yarn.lock) → exit, do nothing
+Otherwise → append one line to .claude/pending-updates.md:
+
+[timestamp] FILE_WRITE: path/to/file — {brief description from tool context}
+This is pure JavaScript/bash. Zero LLM calls. Costs nothing.
+SessionEnd Hook — session-end.js
+Fires when Claude Code session ends.
+Logic:
+
+Read .claude/pending-updates.md
+Count lines
+If 0 lines → print nothing
+If 1-2 lines → print nothing (too minor to surface)
+If 3+ lines → print:
+
+✦ claude-memory: 4 changes logged — run claude-memory update to sync CLAUDE.md
+
+If 10+ lines → print with urgency:
+
+✦ claude-memory: 12 changes logged — CLAUDE.md may be out of date
+  run: claude-memory update
+
+The claude-md-updater Agent
+This is the only part that uses LLM tokens.
+Trigger: Either manually via claude-memory update CLI command, or when developer explicitly asks in Claude Code: "update CLAUDE.md" or "sync claude memory."
+Agent description for Claude Code:
+Use this agent when the user runs claude-memory update, asks to update 
+CLAUDE.md, asks to sync project context, or says "update claude memory". 
+Also triggers when pending-updates.md has 10 or more entries. Does NOT 
+trigger during normal coding work.
+What the agent does:
+
+Reads .claude/pending-updates.md in full
+Reads current CLAUDE.md in full
+For each entry in pending-updates, decides: does this represent a change significant enough to update CLAUDE.md? Criteria:
+
+New file in a key directory (new route, new service, new migration) → yes
+Change to existing file that's already documented → maybe, only if it changes the documented behavior
+Lockfile, config tweak, minor edit → no
+
+
+Makes only surgical edits to CLAUDE.md — adds lines, updates existing lines, never rewrites sections wholesale
+Updates the ## Last Updated line
+Clears .claude/pending-updates.md (writes empty file)
+Prints a one-line summary:
+
+✦ CLAUDE.md updated — 2 entries added, 1 updated, 9 skipped
+Token cost estimate: ~2,000-4,000 tokens per run. At typical API rates, less than $0.01 per update. Run it once a day — negligible.
+
+CLI Commands
+claude-memory init
+First-time setup. Run once per project.
+
+Creates folder structure
+Installs hooks and agent
+Generates CLAUDE.md if missing
+Safe to re-run — won't overwrite existing CLAUDE.md without confirmation
+
+claude-memory status
+Shows current state. Safe to run anytime.
+✦ claude-memory status
+
+  Project:           my-project
+  CLAUDE.md          last updated 2 days ago (Apr 1)
+  Pending updates:   4 changes waiting
+  Last session:      logged 2 changes (today 3:45pm)
+  Agent:             claude-md-updater ✓ installed
+  Hooks:             post-tool-use ✓  session-end ✓
+claude-memory update
+Manually triggers the claude-md-updater agent inside Claude Code.
+
+Only works when run from inside a Claude Code session
+If run outside Claude Code, prints:
+
+✦ claude-memory: open Claude Code and run this command from inside a session,
+  or type "update CLAUDE.md" in your Claude Code chat.
+claude-memory reset
+Clears pending-updates.md without updating CLAUDE.md.
+
+Asks for confirmation first
+Useful if pending changes are all irrelevant
+
+
+package.json
+json{
+  "name": "claude-memory",
+  "version": "0.1.0",
+  "description": "Automatic CLAUDE.md lifecycle management for Claude Code",
+  "bin": {
+    "claude-memory": "./bin/claude-memory.js"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "anthropic",
+    "ai",
+    "developer-tools"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}
+
+What To Build First — Prioritized Order
+Tell Claude Code to build in this order so you have something working at each step:
+
+npm package skeleton — package.json, bin/claude-memory.js, basic CLI routing
+claude-memory init — folder creation, file scaffolding, confirmation output
+claude-memory status — reads state and displays it
+PostToolUse hook — the change logger
+SessionEnd hook — the session summary
+claude-md-updater agent — the CLAUDE.md syncer
+claude-memory update — triggers the agent
+claude-memory reset — clears pending updates
+Polish — error handling, edge cases, first-run experience

package/package.json

@@ -0,0 +1 @@
+{"name":"claude-compass","version":"0.0.1"}