claude-compass 0.1.0 → 0.1.2

package/README.md

@@ -16,13 +16,32 @@ One-line note appended to .claude/pending-updates.md
        ↓
 Session ends → SessionEnd hook prints a summary if 3+ changes logged
        ↓
-You run: claude-compass update  (or type "update CLAUDE.md" in chat)
+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
@@ -47,7 +66,7 @@ This will:
 - 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)
+- Create a `CLAUDE.md` stub if one doesn't exist (leaves any existing one untouched)
 
 ## Commands
 
@@ -104,12 +123,12 @@ Everything else gets a one-line entry in `pending-updates.md`.
 
 ## Updating CLAUDE.md
 
-When you're ready to sync, either:
+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 remind you of the exact phrase to use
+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. It costs roughly 2,000–4,000 tokens per run.
+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
 

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "claude-compass",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Automatic CLAUDE.md lifecycle management for Claude Code",
   "bin": {
-    "claude-compass": "./bin/claude-compass.js"
+    "claude-compass": "bin/claude-compass.js"
   },
   "keywords": [
     "claude",

package/src/init.js

@@ -24,13 +24,6 @@ async function run() {
     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 });