claude-compass 0.0.1 → 0.1.1

package/README.md

@@ -0,0 +1,135 @@
+# claude-compass
+
+Automatic `CLAUDE.md` lifecycle management for [Claude Code](https://claude.ai/code).
+
+Installs hooks and an agent into your project so that `CLAUDE.md` stays accurate as your codebase evolves — silently, without interrupting your workflow.
+
+## How it works
+
+```
+You write code in Claude Code
+       ↓
+PostToolUse hook fires after significant file writes
+       ↓
+One-line note appended to .claude/pending-updates.md
+(pure JS, zero LLM tokens)
+       ↓
+Session ends → SessionEnd hook prints a summary if 3+ changes logged
+       ↓
+You type "update CLAUDE.md" in chat (or run claude-compass update)
+       ↓
+claude-md-updater agent reads pending-updates.md + CLAUDE.md
+Makes surgical updates, clears the log
+Prints: "CLAUDE.md updated — 2 entries added, 1 updated, 9 skipped"
+```
+
+## Why the update step is intentional
+
+The two parts of claude-compass are split deliberately:
+
+- **Logging is fully automatic.** Every file write is captured by the hook with zero effort and zero cost. You never think about it.
+- **Updating is manual.** You decide when to sync — typically at a natural stopping point, once a day, or when finishing a feature.
+
+This split matters because most file edits don't change anything worth documenting. Running the agent after every session would spend tokens deciding "nothing changed" the majority of the time. Triggering it yourself costs about the same tokens but only when it actually has something useful to do.
+
+## Token usage
+
+| Part | Tokens | Frequency |
+|---|---|---|
+| PostToolUse hook | **0** | Every file write |
+| SessionEnd hook | **0** | Every session end |
+| `claude-md-updater` agent | ~2,000–4,000 | Only when you trigger it |
+
+At current API rates, one full sync costs less than **$0.01**. Running it once a day for a year is roughly $2–3 total.
+
+## Requirements
+
+- [Claude Code](https://claude.ai/code) CLI
+- Node.js 18+
+
+## Installation
+
+```bash
+npm install -g claude-compass
+```
+
+## Setup
+
+Run once per project, from the project root:
+
+```bash
+claude-compass init
+```
+
+This will:
+- Create `.claude/pending-updates.md` and `.claude/context/`
+- Copy hooks into `.claude/hooks/`
+- Register hooks in `~/.claude/settings.json`
+- Install the `claude-md-updater` agent into `.claude/agents/`
+- Create a `CLAUDE.md` stub if one doesn't exist (backs up any existing one first)
+
+## Commands
+
+### `claude-compass init`
+First-time setup. Safe to re-run — won't overwrite an existing `CLAUDE.md` without backing it up first.
+
+### `claude-compass status`
+Shows the current state of your project context.
+
+```
+✦ claude-compass status
+
+  Project:           my-project
+  CLAUDE.md          last updated 2 days ago (Apr 1)
+  Pending updates:   4 changes waiting
+  Last session:      logged changes (today 3:45 PM)
+  Agent:             claude-md-updater ✓ installed
+  Hooks:             post-tool-use ✓  session-end ✓
+```
+
+### `claude-compass update`
+Tells you how to trigger the `claude-md-updater` agent from inside Claude Code. The actual update is done by the agent (requires a Claude Code session).
+
+### `claude-compass reset`
+Clears `pending-updates.md` without updating `CLAUDE.md`. Asks for confirmation. Use `-y` to skip.
+
+```bash
+claude-compass reset -y
+```
+
+## File structure after init
+
+```
+your-project/
+├── CLAUDE.md                        ← stable project context
+└── .claude/
+    ├── pending-updates.md           ← append-only change log (auto-managed)
+    ├── agents/
+    │   └── claude-md-updater.md     ← the updater agent
+    ├── hooks/
+    │   ├── post-tool-use.js         ← logs significant file writes
+    │   └── session-end.js           ← prints session summary
+    └── context/                     ← optional reference files
+```
+
+## What gets logged
+
+The `post-tool-use` hook fires after every `Write`, `Edit`, or `MultiEdit` tool call in Claude Code. It ignores:
+
+- `node_modules/`, `.git/`, `dist/`, `build/`, `.next/`
+- Lockfiles (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, etc.)
+
+Everything else gets a one-line entry in `pending-updates.md`.
+
+## Updating CLAUDE.md
+
+When the session-end hook reminds you there are pending changes, either:
+
+1. Type `update CLAUDE.md` in the Claude Code chat, or
+2. Run `claude-compass update` in the terminal — it will show you exactly what to type
+
+The `claude-md-updater` agent reads the pending log, decides what's significant enough to document, makes surgical edits to `CLAUDE.md`, and clears the log.
+
+## License
+
+MIT

package/bin/claude-compass.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+'use strict';
+
+const [,, command, ...args] = process.argv;
+
+const commands = {
+  init:   () => require('../src/init.js').run(args),
+  status: () => require('../src/status.js').run(args),
+  update: () => require('../src/update.js').run(args),
+  reset:  () => require('../src/reset.js').run(args),
+};
+
+if (!command || command === '--help' || command === '-h') {
+  printHelp();
+  process.exit(0);
+}
+
+if (command === '--version' || command === '-v') {
+  const pkg = require('../package.json');
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+if (!commands[command]) {
+  console.error(`claude-compass: unknown command '${command}'`);
+  console.error(`Run 'claude-compass --help' for usage.`);
+  process.exit(1);
+}
+
+commands[command]().catch(err => {
+  console.error(`claude-compass: ${err.message}`);
+  process.exit(1);
+});
+
+function printHelp() {
+  console.log(`claude-compass — CLAUDE.md lifecycle management for Claude Code
+
+Usage:
+  claude-compass init      First-time setup. Creates structure, installs hooks and agent.
+  claude-compass status    Show current state of pending updates and hooks.
+  claude-compass update    Trigger the claude-md-updater agent to sync CLAUDE.md.
+  claude-compass reset     Clear pending-updates.md without updating CLAUDE.md.
+
+Options:
+  -h, --help       Show this help message
+  -v, --version    Show version number
+`);
+}

package/package.json

@@ -1 +1,25 @@
-{"name":"claude-compass","version":"0.0.1"}
+{
+  "name": "claude-compass",
+  "version": "0.1.1",
+  "description": "Automatic CLAUDE.md lifecycle management for Claude Code",
+  "bin": {
+    "claude-compass": "bin/claude-compass.js"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "anthropic",
+    "ai",
+    "developer-tools"
+  ],
+  "author": "codemode001",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates"
+  ]
+}

package/src/init.js

@@ -0,0 +1,161 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+
+const PKG_DIR = path.join(__dirname, '..');
+
+async function run() {
+  const cwd = process.cwd();
+  const claudeDir = path.join(cwd, '.claude');
+  const contextDir = path.join(claudeDir, 'context');
+  const pendingPath = path.join(claudeDir, 'pending-updates.md');
+  const agentsDir = path.join(claudeDir, 'agents');
+  const hooksDir = path.join(claudeDir, 'hooks');
+  const claudeMdPath = path.join(cwd, 'CLAUDE.md');
+
+  const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+
+  // Warn if not a git repo
+  if (!fs.existsSync(path.join(cwd, '.git'))) {
+    console.warn('  Warning: current directory does not appear to be a git repository.');
+    console.warn('  claude-compass works best inside a git repo, but continuing anyway.\n');
+  }
+
+  // Backup existing CLAUDE.md
+  if (fs.existsSync(claudeMdPath)) {
+    const backupPath = claudeMdPath + '.backup';
+    fs.copyFileSync(claudeMdPath, backupPath);
+    console.log(`  Backed up existing CLAUDE.md → CLAUDE.md.backup`);
+  }
+
+  // Create .claude directories
+  fs.mkdirSync(contextDir, { recursive: true });
+  fs.mkdirSync(agentsDir, { recursive: true });
+  fs.mkdirSync(hooksDir, { recursive: true });
+
+  // Create pending-updates.md if missing
+  if (!fs.existsSync(pendingPath)) {
+    fs.writeFileSync(pendingPath, '', 'utf8');
+  }
+
+  // Install project-level hooks (copies of templates)
+  const hookSrc = path.join(PKG_DIR, 'templates', 'hooks');
+  installHook(path.join(hookSrc, 'post-tool-use.js'), path.join(hooksDir, 'post-tool-use.js'));
+  installHook(path.join(hookSrc, 'session-end.js'), path.join(hooksDir, 'session-end.js'));
+
+  // Register hooks in ~/.claude/settings.json
+  registerHooksInSettings(settingsPath, cwd);
+
+  // Install agent
+  const agentSrc = path.join(PKG_DIR, 'templates', 'agents', 'claude-md-updater.md');
+  const agentDest = path.join(agentsDir, 'claude-md-updater.md');
+  fs.copyFileSync(agentSrc, agentDest);
+
+  // Create CLAUDE.md if missing
+  if (!fs.existsSync(claudeMdPath)) {
+    const stub = buildClaudeMdStub(cwd);
+    fs.writeFileSync(claudeMdPath, stub, 'utf8');
+  }
+
+  // Print confirmation
+  console.log(`\n✦ claude-compass initialized\n`);
+  console.log(`  CLAUDE.md          ✓ ready`);
+  console.log(`  pending-updates    ✓ ready`);
+  console.log(`  hooks              ✓ post-tool-use, session-end registered`);
+  console.log(`  agent              ✓ claude-md-updater installed`);
+  console.log(`\n  Changes will be logged silently during sessions.`);
+  console.log(`  Run: claude-compass status  to check anytime.\n`);
+}
+
+function installHook(src, dest) {
+  fs.copyFileSync(src, dest);
+  fs.chmodSync(dest, 0o755);
+}
+
+function registerHooksInSettings(settingsPath, projectCwd) {
+  // Ensure ~/.claude directory exists
+  const claudeGlobal = path.join(os.homedir(), '.claude');
+  fs.mkdirSync(claudeGlobal, { recursive: true });
+
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    } catch {
+      settings = {};
+    }
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+
+  const postToolUsePath = path.join(projectCwd, '.claude', 'hooks', 'post-tool-use.js');
+  const sessionEndPath = path.join(projectCwd, '.claude', 'hooks', 'session-end.js');
+
+  // PostToolUse hook — correct Claude Code format: { matcher, hooks: [{ type, command }] }
+  if (!settings.hooks.PostToolUse) settings.hooks.PostToolUse = [];
+  const postHookCmd = `node "${postToolUsePath}"`;
+  const hasPost = settings.hooks.PostToolUse.some(entry =>
+    Array.isArray(entry.hooks) && entry.hooks.some(h => h.command === postHookCmd)
+  );
+  if (!hasPost) {
+    settings.hooks.PostToolUse.push({
+      matcher: 'Write|Edit|MultiEdit',
+      hooks: [{ type: 'command', command: postHookCmd }],
+    });
+  }
+
+  // Stop hook (session end)
+  if (!settings.hooks.Stop) settings.hooks.Stop = [];
+  const stopHookCmd = `node "${sessionEndPath}"`;
+  const hasStop = settings.hooks.Stop.some(entry =>
+    Array.isArray(entry.hooks) && entry.hooks.some(h => h.command === stopHookCmd)
+  );
+  if (!hasStop) {
+    settings.hooks.Stop.push({
+      matcher: '',
+      hooks: [{ type: 'command', command: stopHookCmd }],
+    });
+  }
+
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+}
+
+function buildClaudeMdStub(cwd) {
+  const projectName = path.basename(cwd);
+  const date = new Date().toISOString().slice(0, 10);
+  return `# ${projectName}
+
+## Purpose
+
+<!-- Describe what this project does in 1-2 sentences -->
+
+## Tech Stack
+
+<!-- List main languages, frameworks, and key libraries -->
+
+## Architecture
+
+<!-- Key architectural decisions and patterns -->
+
+## Coding Conventions
+
+<!-- Naming conventions, patterns, things to know -->
+
+## Folder Structure
+
+<!-- Brief overview of important directories -->
+
+## Critical Gotchas
+
+<!-- Things that are easy to get wrong or that burned you before -->
+
+## Last Updated
+
+${date}
+`;
+}
+
+module.exports = { run };

package/src/reset.js

@@ -0,0 +1,54 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+async function run(args) {
+  const cwd = process.cwd();
+  const pendingPath = path.join(cwd, '.claude', 'pending-updates.md');
+
+  if (!fs.existsSync(pendingPath)) {
+    console.error(`claude-compass: .claude/pending-updates.md not found.`);
+    console.error(`Run 'claude-compass init' first.`);
+    process.exit(1);
+  }
+
+  const content = fs.readFileSync(pendingPath, 'utf8').trim();
+  const lines = content ? content.split('\n').filter(l => l.trim()) : [];
+
+  if (lines.length === 0) {
+    console.log(`✦ claude-compass: pending-updates.md is already empty. Nothing to reset.`);
+    process.exit(0);
+  }
+
+  // --yes / -y skips confirmation
+  const skipConfirm = args.includes('--yes') || args.includes('-y');
+
+  if (!skipConfirm) {
+    console.log(`\n  This will discard ${lines.length} pending change${lines.length === 1 ? '' : 's'} without updating CLAUDE.md.\n`);
+    const confirmed = await confirm(`  Are you sure? [y/N] `);
+    if (!confirmed) {
+      console.log(`  Aborted. Nothing was changed.\n`);
+      process.exit(0);
+    }
+  }
+
+  fs.writeFileSync(pendingPath, '', 'utf8');
+  console.log(`\n✦ claude-compass: pending-updates.md cleared (${lines.length} entr${lines.length === 1 ? 'y' : 'ies'} discarded).\n`);
+}
+
+function confirm(prompt) {
+  return new Promise(resolve => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    rl.question(prompt, answer => {
+      rl.close();
+      resolve(answer.trim().toLowerCase() === 'y');
+    });
+  });
+}
+
+module.exports = { run };

package/src/status.js

@@ -0,0 +1,90 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+async function run() {
+  const cwd = process.cwd();
+  const projectName = path.basename(cwd);
+  const claudeDir = path.join(cwd, '.claude');
+  const pendingPath = path.join(claudeDir, 'pending-updates.md');
+  const agentPath = path.join(claudeDir, 'agents', 'claude-md-updater.md');
+  const postHookPath = path.join(claudeDir, 'hooks', 'post-tool-use.js');
+  const sessionHookPath = path.join(claudeDir, 'hooks', 'session-end.js');
+  const claudeMdPath = path.join(cwd, 'CLAUDE.md');
+
+  console.log(`\n✦ claude-compass status\n`);
+  console.log(`  Project:           ${projectName}`);
+
+  // CLAUDE.md age
+  if (fs.existsSync(claudeMdPath)) {
+    const stat = fs.statSync(claudeMdPath);
+    const age = formatAge(stat.mtime);
+    console.log(`  CLAUDE.md          last updated ${age}`);
+  } else {
+    console.log(`  CLAUDE.md          ✗ not found — run claude-compass init`);
+  }
+
+  // Pending updates
+  if (fs.existsSync(pendingPath)) {
+    const content = fs.readFileSync(pendingPath, 'utf8').trim();
+    const lines = content ? content.split('\n').filter(l => l.trim()) : [];
+    if (lines.length === 0) {
+      console.log(`  Pending updates:   none`);
+    } else {
+      console.log(`  Pending updates:   ${lines.length} change${lines.length === 1 ? '' : 's'} waiting`);
+    }
+
+    // Last session: find last timestamp
+    if (lines.length > 0) {
+      const lastLine = lines[lines.length - 1];
+      const match = lastLine.match(/^\[(\d{4}-\d{2}-\d{2} \d{2}:\d{2})\]/);
+      if (match) {
+        const ts = new Date(match[1]);
+        const age = formatAge(ts);
+        console.log(`  Last session:      logged changes (${age})`);
+      }
+    }
+  } else {
+    console.log(`  Pending updates:   ✗ not found — run claude-compass init`);
+  }
+
+  // Agent
+  const agentInstalled = fs.existsSync(agentPath);
+  console.log(`  Agent:             claude-md-updater ${agentInstalled ? '✓ installed' : '✗ not found'}`);
+
+  // Hooks
+  const postOk = fs.existsSync(postHookPath);
+  const sessionOk = fs.existsSync(sessionHookPath);
+  const hooksStr = [
+    `post-tool-use ${postOk ? '✓' : '✗'}`,
+    `session-end ${sessionOk ? '✓' : '✗'}`,
+  ].join('  ');
+  console.log(`  Hooks:             ${hooksStr}`);
+
+  if (!postOk || !sessionOk || !agentInstalled) {
+    console.log(`\n  Some components are missing. Run: claude-compass init`);
+  }
+
+  console.log('');
+}
+
+function formatAge(date) {
+  const now = Date.now();
+  const diff = now - date.getTime();
+  const minutes = Math.floor(diff / 60000);
+  const hours = Math.floor(diff / 3600000);
+  const days = Math.floor(diff / 86400000);
+
+  const timeStr = date.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+  const dateStr = date.toLocaleDateString([], { month: 'short', day: 'numeric' });
+
+  if (minutes < 1) return 'just now';
+  if (minutes < 60) return `${minutes} minute${minutes === 1 ? '' : 's'} ago (today ${timeStr})`;
+  if (hours < 24) return `${hours} hour${hours === 1 ? '' : 's'} ago (today ${timeStr})`;
+  if (days === 1) return `1 day ago (${dateStr})`;
+  return `${days} days ago (${dateStr})`;
+}
+
+module.exports = { run };

package/src/update.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+async function run() {
+  const cwd = process.cwd();
+  const pendingPath = path.join(cwd, '.claude', 'pending-updates.md');
+
+  if (!fs.existsSync(pendingPath)) {
+    console.error(`claude-compass: .claude/pending-updates.md not found.`);
+    console.error(`Run 'claude-compass init' first.`);
+    process.exit(1);
+  }
+
+  const content = fs.readFileSync(pendingPath, 'utf8').trim();
+  const lines = content ? content.split('\n').filter(l => l.trim()) : [];
+
+  if (lines.length === 0) {
+    console.log(`✦ claude-compass: nothing to update — pending-updates.md is empty`);
+    process.exit(0);
+  }
+
+  // When invoked as a CLI command from inside Claude Code, Claude Code itself
+  // will see this output and can invoke the agent. The update command just
+  // signals intent — the actual LLM work is done by the claude-md-updater agent.
+  console.log(`\n✦ claude-compass: ${lines.length} pending change${lines.length === 1 ? '' : 's'} found`);
+  console.log(`\n  To sync CLAUDE.md, type the following in your Claude Code chat:`);
+  console.log(`\n    update CLAUDE.md\n`);
+  console.log(`  The claude-md-updater agent will read pending-updates.md and make`);
+  console.log(`  surgical updates to CLAUDE.md, then clear the pending log.\n`);
+}
+
+module.exports = { run };

package/templates/agents/claude-md-updater.md

@@ -0,0 +1,60 @@
+---
+name: claude-md-updater
+description: Use this agent when the user runs `claude-compass update`, explicitly asks to update CLAUDE.md, asks to sync project context, or says "update claude compass" / "sync claude compass". Also triggers when pending-updates.md has 10 or more entries. Does NOT trigger during normal coding work, file edits, debugging sessions, or any task that was not an explicit request to update CLAUDE.md.
+---
+
+You are the claude-md-updater agent. Your only job is to make surgical, accurate updates to CLAUDE.md based on what actually changed during recent coding sessions.
+
+## Your inputs
+
+1. `.claude/pending-updates.md` — an append-only log of file writes that happened since the last update
+2. `CLAUDE.md` — the project context file you will update
+
+## Process
+
+**Step 1 — Read both files in full.**
+
+Read `.claude/pending-updates.md` and `CLAUDE.md`. If pending-updates.md is empty or missing, print:
+
+```
+✦ claude-compass: nothing to update — pending-updates.md is empty
+```
+
+Then stop.
+
+**Step 2 — Evaluate each pending entry.**
+
+For each line in pending-updates.md, decide whether it represents a change significant enough to update CLAUDE.md. Apply these criteria strictly:
+
+- New file in a key directory (new route, new service, new migration, new component) → **yes, update**
+- Change to an existing file that's already documented in CLAUDE.md AND the change alters the documented behavior → **maybe, update only if the documented fact is now wrong**
+- Lockfile, build output, config tweak, minor edit to an already-documented file → **no, skip**
+- Changes to test files → **only if they reveal a new testing convention not yet documented**
+
+When in doubt, skip. CLAUDE.md should contain stable facts, not a changelog.
+
+**Step 3 — Make surgical edits to CLAUDE.md.**
+
+- Add new lines where appropriate — under the relevant section heading
+- Update existing lines only if the documented fact is now incorrect
+- Never rewrite entire sections wholesale
+- Never delete existing content unless it is demonstrably wrong
+- Keep CLAUDE.md concise — it should be scannable in under 2 minutes
+- Update the `## Last Updated` line at the bottom with today's date
+
+**Step 4 — Clear pending-updates.md.**
+
+Write an empty string to `.claude/pending-updates.md` (overwrite with empty content).
+
+**Step 5 — Print a one-line summary.**
+
+```
+✦ CLAUDE.md updated — X entries added, Y updated, Z skipped
+```
+
+## Hard constraints
+
+- Do not invent facts. Only document what is directly evidenced by the pending entries or already in CLAUDE.md.
+- Do not add speculative architecture, planned features, or inferred conventions unless you have direct evidence.
+- Do not add verbose explanations — CLAUDE.md entries should be 1-2 lines each.
+- This agent must not trigger during normal coding. It only runs when explicitly invoked.

package/templates/hooks/post-tool-use.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+'use strict';
+
+// PostToolUse hook for claude-compass
+// Fires after every Claude Code tool use.
+// Appends one line to .claude/pending-updates.md for significant file writes.
+// Zero LLM calls. Pure JavaScript.
+
+const fs = require('fs');
+const path = require('path');
+
+function main() {
+  let input = '';
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => { input += chunk; });
+  process.stdin.on('end', () => {
+    try {
+      run(input.trim());
+    } catch (err) {
+      // Hooks must never crash Claude Code — exit silently
+      process.exit(0);
+    }
+  });
+}
+
+function run(rawInput) {
+  let event;
+  try {
+    event = JSON.parse(rawInput);
+  } catch {
+    process.exit(0);
+  }
+
+  const toolName = event?.tool_name || event?.tool || '';
+  const toolInput = event?.tool_input || event?.input || {};
+
+  // Only act on file-write tools
+  const writeTools = ['Write', 'Edit', 'MultiEdit'];
+  if (!writeTools.includes(toolName)) {
+    process.exit(0);
+  }
+
+  // Get the file path written
+  const filePath = toolInput?.file_path || toolInput?.path || '';
+  if (!filePath) {
+    process.exit(0);
+  }
+
+  // Ignore noisy paths
+  const ignoredSegments = [
+    'node_modules/',
+    '.git/',
+    '/dist/',
+    '/build/',
+    '/.next/',
+    '/out/',
+    '/coverage/',
+    '/__pycache__/',
+    '/vendor/',
+  ];
+  const normalised = filePath.replace(/\\/g, '/');
+  if (ignoredSegments.some(seg => normalised.includes(seg))) {
+    process.exit(0);
+  }
+
+  // Ignore lockfiles
+  const lockfiles = [
+    'package-lock.json',
+    'yarn.lock',
+    'pnpm-lock.yaml',
+    'bun.lockb',
+    'Gemfile.lock',
+    'poetry.lock',
+    'Pipfile.lock',
+    'composer.lock',
+    'go.sum',
+  ];
+  const basename = path.basename(filePath);
+  if (lockfiles.includes(basename)) {
+    process.exit(0);
+  }
+
+  // Build a brief description from context
+  const description = buildDescription(toolName, toolInput, filePath);
+
+  // Resolve pending-updates.md relative to cwd (project root)
+  const pendingPath = path.join(process.cwd(), '.claude', 'pending-updates.md');
+
+  // If the file doesn't exist yet the project isn't initialised — skip silently
+  if (!fs.existsSync(pendingPath)) {
+    process.exit(0);
+  }
+
+  const timestamp = new Date().toISOString().slice(0, 16).replace('T', ' ');
+  const line = `[${timestamp}] FILE_WRITE: ${filePath} — ${description}\n`;
+
+  fs.appendFileSync(pendingPath, line, 'utf8');
+  process.exit(0);
+}
+
+function buildDescription(toolName, toolInput, filePath) {
+  if (toolName === 'Write') {
+    return `file written`;
+  }
+  if (toolName === 'Edit') {
+    return `file edited`;
+  }
+  if (toolName === 'MultiEdit') {
+    const count = (toolInput?.edits || []).length;
+    return count > 1 ? `${count} edits applied` : `file edited`;
+  }
+  return `modified`;
+}
+
+main();

package/templates/hooks/session-end.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+'use strict';
+
+// SessionEnd hook for claude-compass
+// Fires when a Claude Code session ends.
+// Prints a summary if 3+ changes were logged during the session.
+// Zero LLM calls. Pure JavaScript.
+
+const fs = require('fs');
+const path = require('path');
+
+function main() {
+  try {
+    run();
+  } catch {
+    process.exit(0);
+  }
+}
+
+function run() {
+  const pendingPath = path.join(process.cwd(), '.claude', 'pending-updates.md');
+
+  if (!fs.existsSync(pendingPath)) {
+    process.exit(0);
+  }
+
+  const content = fs.readFileSync(pendingPath, 'utf8').trim();
+  if (!content) {
+    process.exit(0);
+  }
+
+  const lines = content.split('\n').filter(l => l.trim().length > 0);
+  const count = lines.length;
+
+  if (count < 3) {
+    process.exit(0);
+  }
+
+  if (count >= 10) {
+    console.log(`\n✦ claude-compass: ${count} changes logged — CLAUDE.md may be out of date`);
+    console.log(`  run: claude-compass update\n`);
+  } else {
+    console.log(`\n✦ claude-compass: ${count} changes logged — run claude-compass update to sync CLAUDE.md\n`);
+  }
+
+  process.exit(0);
+}
+
+main();

package/claude-compass-spec.md

@@ -1,217 +0,0 @@
-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