claudectx 1.1.1 → 1.1.3

package/README.md

@@ -80,12 +80,29 @@ claudectx convert --to cursor
 
 # Export your usage data for team-wide cost attribution
 claudectx teams export
+
+# --- Safety: every command that modifies files backs up automatically ---
+
+# See all automatic backups
+claudectx revert --list
+
+# Restore any backup (also backs up current file so you can undo the undo)
+claudectx revert --id <id>
 ```
 
 ## Installation
 
 ```bash
+# npm (recommended)
 npm install -g claudectx
+
+# Homebrew
+brew tap Horilla/claudectx
+brew install claudectx
+
+# pip (Python projects)
+pip install claudectx-py
+# then: npm install -g claudectx  (the npm package is still required)
 ```
 
 ---
@@ -154,6 +171,8 @@ What it does:
 - **Cache advisor** — Finds date strings, timestamps, and other patterns that break prompt caching and comments them out.
 - **Hooks installer** — Installs a `PostToolUse` hook in `.claude/settings.local.json` so `claudectx watch` can track files in real time.
 
+> **Safety:** `optimize` backs up your `CLAUDE.md` automatically before any changes. Run `claudectx revert --list` to restore.
+
 ---
 
 ### `claudectx watch` — Live token dashboard
@@ -214,6 +233,8 @@ claudectx compress --api-key <key>        # Provide API key explicitly
 
 A typical 8,000-token session compresses to ~180 tokens — **97.8% reduction**.
 
+> **Safety:** `compress --prune` asks for confirmation before deleting entries and backs up `MEMORY.md` first. Run `claudectx revert --list` to restore.
+
 ---
 
 ### `claudectx report` — Usage analytics
@@ -269,14 +290,17 @@ Output shows per-file token counts, cache hit likelihood (based on your recent r
 Start each session with a cache hit instead of a full miss. Sends a silent priming request to Anthropic so your CLAUDE.md is cached before Claude Code touches it.
 
 ```bash
-claudectx warmup --api-key $ANTHROPIC_API_KEY         # 5-min cache TTL (default)
-claudectx warmup --ttl 60 --api-key $ANTHROPIC_API_KEY  # 60-min extended TTL
-claudectx warmup --cron "0 9 * * 1-5" --api-key ...  # Install as daily cron job
-claudectx warmup --json                               # Output result as JSON
+claudectx warmup --api-key $ANTHROPIC_API_KEY          # 5-min cache TTL (default)
+claudectx warmup --ttl 60 --api-key $ANTHROPIC_API_KEY # 60-min extended TTL (2× write cost)
+claudectx warmup --model sonnet --api-key $ANTHROPIC_API_KEY  # use a specific model
+claudectx warmup --cron "0 9 * * 1-5"                 # Install as weekday 9am cron job
+claudectx warmup --json                                # JSON output for scripting
 ```
 
 Reports tokens warmed, write cost, savings per cache hit, and break-even request count.
 
+> **Note on `--cron`:** The API key is **not** embedded in the cron job. At runtime, the job reads `ANTHROPIC_API_KEY` from your environment. Set it in `~/.profile` or `~/.zshenv` so cron can see it.
+
 ---
 
 ### `claudectx drift` — CLAUDE.md stays fresh, not stale
@@ -286,8 +310,9 @@ Over time CLAUDE.md accumulates dead references and sections nobody reads. `drif
 ```bash
 claudectx drift                      # Scan current project
 claudectx drift --days 14            # Use 14-day read window (default: 30)
-claudectx drift --fix                # Interactively remove flagged lines
+claudectx drift --fix                # Interactively remove flagged lines (creates CLAUDE.md.bak first)
 claudectx drift --json               # JSON output
+claudectx drift --path /other/proj  # Scan a different project directory
 ```
 
 Detects 4 types of drift:
@@ -306,20 +331,26 @@ Detects 4 types of drift:
 Install named, pre-configured hooks beyond the basic read logger.
 
 ```bash
-claudectx hooks list                                  # Show all available hooks
-claudectx hooks add auto-compress --config apiKey=sk-...  # Install a hook
-claudectx hooks remove slack-digest                   # Remove an installed hook
-claudectx hooks status                                # Show what's installed
+claudectx hooks list                                        # Show all available hooks
+claudectx hooks add auto-compress                           # Install with default threshold (50k tokens)
+claudectx hooks add auto-compress --config threshold=30000  # Custom token threshold
+claudectx hooks add slack-digest --config webhookUrl=https://hooks.slack.com/...
+claudectx hooks remove slack-digest                         # Remove an installed hook
+claudectx hooks status                                      # Show what's installed
 ```
 
 **Built-in hooks:**
 
-| Hook | Trigger | What it does |
-|---|---|---|
-| `auto-compress` | PostToolUse (Read) | Runs `claudectx compress` after each session |
-| `daily-budget` | PreToolUse | Checks token budget before each tool call |
-| `slack-digest` | Stop | Posts session report to a Slack webhook |
-| `session-warmup` | PostToolUse (Read) | Re-warms the cache after each read |
+| Hook | Trigger | Config | What it does |
+|---|---|---|---|
+| `auto-compress` | PostToolUse (Read) | `threshold` (default: 50000) | Runs `claudectx compress` after each session |
+| `daily-budget` | PreToolUse | _(none)_ | Reports today's spend before each tool call |
+| `slack-digest` | Stop | `webhookUrl` (required) | Posts session report to a Slack webhook |
+| `session-warmup` | PostToolUse (Read) | _(none)_ | Re-warms the cache; reads `ANTHROPIC_API_KEY` from env |
+
+> **Security note:** Hooks that need an API key (`compress`, `warmup`) read `ANTHROPIC_API_KEY` from your environment — no secrets are stored in `.claude/settings.local.json`.
+
+> **Safety:** `hooks remove` asks for confirmation and backs up `.claude/settings.local.json` before removing. Run `claudectx revert --list` to restore.
 
 ---
 
@@ -336,6 +367,8 @@ claudectx convert --to cursor --dry-run  # Preview without writing
 
 Each `##` section in CLAUDE.md becomes a separate Cursor `.mdc` file with `alwaysApply: true` frontmatter. `@file` references are stripped for assistants that don't support them.
 
+> **Safety:** `convert` backs up any existing target file before overwriting. Run `claudectx revert --list` to restore.
+
 ---
 
 ### `claudectx teams` — Multi-developer cost attribution
@@ -344,22 +377,68 @@ See where the money goes across your whole team — without sharing session cont
 
 ```bash
 # Step 1: each developer runs this on their own machine
-claudectx teams export
+claudectx teams export                           # Default: last 30 days, sonnet pricing
+claudectx teams export --days 7 --model haiku   # Custom window and model
 
 # Step 2: collect the JSON files in a shared directory, then aggregate
 claudectx teams aggregate --dir ./reports/
+claudectx teams aggregate --dir ./reports/ --anonymize  # Replace names with Dev 1, Dev 2...
+claudectx teams aggregate --dir ./reports/ --json       # Machine-readable JSON
 
 # Optional: copy your export to a shared location
 claudectx teams share --to /shared/reports/
-
-# Anonymize for review
-claudectx teams aggregate --dir ./reports/ --anonymize
 ```
 
 Output shows per-developer spend, cache hit rate, avg request size, and top shared files. Exports are lightweight JSON — no session content, no prompts, just aggregated token counts.
 
 ---
 
+### `claudectx revert` — Restore any backup
+
+Every command that modifies your files creates an automatic backup in `~/.claudectx/backups/` before touching anything. If something goes wrong — or you just changed your mind — you can always recover.
+
+```bash
+claudectx revert --list         # See all backups with timestamps and size
+claudectx revert --id <id>      # Restore a specific backup
+claudectx revert                # Interactive: pick from list
+claudectx revert --file CLAUDE.md  # Filter to backups of one file
+```
+
+Example output of `claudectx revert --list`:
+
+```
+claudectx — Backup History
+══════════════════════════════════════════════════════════════════
+  ID                          File                Command     When
+──────────────────────────────────────────────────────────────────
+  20260412T083012m445-1842...  CLAUDE.md           optimize    2 hours ago
+  20260411T211533m102-9913...  MEMORY.md           compress    1 day ago
+  20260411T094201m773-3371...  copilot-instr...    convert     2 days ago
+```
+
+When you restore, claudectx backs up the **current** file first — so you can undo the undo:
+
+```
+⚠  This will overwrite /path/to/CLAUDE.md with the backup from 2 hours ago.
+   Your current file will be backed up first (so you can undo this).
+   Restore? [y/N]
+```
+
+**Safety:** Backups are kept for the 50 most recent operations, then auto-pruned. They are stored only on your local machine.
+
+**Which commands create backups automatically:**
+
+| Command | What gets backed up |
+|---|---|
+| `optimize --claudemd` | `CLAUDE.md` (before split) |
+| `optimize --cache` | `CLAUDE.md` (before cache-busting lines are commented out) |
+| `convert --to X` | Existing Cursor/Copilot/Windsurf config (if it exists) |
+| `compress --prune` | `MEMORY.md` (before old entries are deleted) |
+| `hooks remove` | `.claude/settings.local.json` (before hook is removed) |
+| `drift --fix` | `CLAUDE.md.bak` (existing behaviour, now also in manifest) |
+
+---
+
 ## How it all fits together
 
 ```
@@ -379,7 +458,7 @@ End of session:                      End of session:
 
 ## Token Savings — Share Your Results
 
-Join the **[Token Savings Hall of Fame](https://github.com/Horilla/claudectx/discussions)** — share your before/after numbers.
+Join the **[Token Savings Hall of Fame](HALL_OF_FAME.md)** — share your before/after numbers and see real results from other developers.
 
 ---
 
@@ -392,7 +471,7 @@ git clone https://github.com/Horilla/claudectx.git
 cd claudectx
 npm install
 npm run build
-npm test          # 278 tests, should all pass
+npm test          # 293 tests, should all pass
 npm run lint      # 0 errors expected
 ```