claude-compass

Automatic CLAUDE.md lifecycle management for Claude 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 entry appended to .claude/pending-updates.md
with file path + code snippet (pure JS, zero LLM tokens)
       ↓
Next session → PreToolUse hook reminds you if 3+ changes are pending
       ↓
You say "update CLAUDE.md" in chat (or run claude-compass update)
       ↓
claude-md-updater agent reads the log, reads changed files,
makes surgical updates to CLAUDE.md, 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 | |---|---|---| | PreToolUse hook | 0 | First tool call per session | | 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 CLI
• Node.js 18+

Installation

npm install -g claude-compass

Setup

Run once per project, from the project root:

claude-compass init

This will:

• Create .claude/pending-updates.md and .claude/context/
• Copy hooks into .claude/hooks/ (pre-tool-use, post-tool-use, session-end)
• Register hooks in ~/.claude/settings.json
• Install the claude-md-updater agent into .claude/agents/
• Add local state files to .gitignore
• Create a CLAUDE.md stub if one doesn't exist (leaves any existing one untouched)

Upgrading

When a new version of claude-compass is released:

npm update -g claude-compass
claude-compass upgrade

The upgrade command re-copies hooks and the agent from the latest package version. It does not touch your CLAUDE.md or pending-updates.md.

Commands

claude-compass init

First-time setup. Safe to re-run — won't overwrite an existing CLAUDE.md.

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:             pre-tool-use ✓  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.

claude-compass reset -y

claude-compass upgrade

Re-copies hooks and the agent from the latest installed package version. Run this after npm update -g claude-compass to refresh your project's hooks.

What gets logged

The post-tool-use hook fires after every Write, Edit, or MultiEdit tool call in Claude Code. Each entry includes the relative file path and a code snippet showing what changed.

[2026-04-04 13:23] EDIT: Hubs/ChatHub.cs — "public async Task SendMessage(string userId, string msg)"
[2026-04-04 13:24] WRITE: src/services/auth.js — new file (42 lines): "import jwt from 'jsonwebtoken'"
[2026-04-04 13:30] MULTI_EDIT: src/routes/api.js — 3 edits: "app.post('/webhook'...", "added rate limiter..."

It ignores:

• node_modules/, .git/, dist/, build/, .next/
• Lockfiles (package-lock.json, yarn.lock, pnpm-lock.yaml, etc.)

Updating CLAUDE.md

When the pre-tool-use hook reminds you there are pending changes, either:

1. Say 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, reads the actual changed files to verify significance, makes surgical edits to CLAUDE.md, and clears the log.

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/
    │   ├── pre-tool-use.cjs         <- session-start reminder
    │   ├── post-tool-use.cjs        <- logs file writes with snippets
    │   └── session-end.cjs          <- prints session summary
    └── context/                     <- optional reference files

License

MIT