@ricky-stevens/context-guardian 2.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,29 @@
+{
+	"name": "context-guardian",
+	"owner": {
+		"name": "Ricky Stevens",
+		"email": ""
+	},
+	"plugins": [
+		{
+			"name": "cg",
+			"source": "./",
+			"description": "Automatic context window monitoring and smart compaction for Claude Code",
+			"version": "2.1.0",
+			"author": {
+				"name": "Ricky"
+			},
+			"homepage": "https://github.com/Ricky-Stevens/context-guardian",
+			"repository": "https://github.com/Ricky-Stevens/context-guardian",
+			"license": "MIT",
+			"keywords": [
+				"context",
+				"tokens",
+				"compaction",
+				"memory",
+				"context-window"
+			],
+			"category": "productivity"
+		}
+	]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,63 @@
+{
+	"name": "cg",
+	"version": "2.1.0",
+	"description": "Automatic context window monitoring and smart compaction for Claude Code",
+	"author": {
+		"name": "Ricky Stevens",
+		"url": "https://github.com/Ricky-Stevens"
+	},
+	"repository": "https://github.com/Ricky-Stevens/context-guardian",
+	"license": "MIT",
+	"keywords": ["context", "tokens", "compaction", "memory", "context-window"],
+	"category": "productivity",
+	"tags": ["context-management", "smart-compact", "token-monitoring"],
+
+	"skills": "./skills/",
+
+	"hooks": {
+		"SessionStart": [
+			{
+				"matcher": "",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/session-start.mjs"
+					}
+				]
+			}
+		],
+		"UserPromptSubmit": [
+			{
+				"matcher": "",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/submit.mjs"
+					}
+				]
+			}
+		],
+		"PreCompact": [
+			{
+				"matcher": "",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/precompact.mjs"
+					}
+				]
+			}
+		],
+		"Stop": [
+			{
+				"matcher": "",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/stop.mjs"
+					}
+				]
+			}
+		]
+	}
+}

package/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bunx biome check hooks/ lib/
+
+  test:
+    name: Test (Bun)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bun test
+      - name: Generate coverage
+        run: bun test --coverage --coverage-reporter=lcov --coverage-dir=coverage
+      - uses: actions/upload-artifact@v4
+        with:
+          name: coverage
+          path: coverage/lcov.info
+
+  test-node:
+    name: Test (Node ${{ matrix.node-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20, 22, 24]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: node --test test/*.test.mjs
+
+  sonarcloud:
+    name: SonarCloud Analysis
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/download-artifact@v4
+        with:
+          name: coverage
+          path: coverage
+      - uses: SonarSource/sonarqube-scan-action@v6
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

package/CLAUDE.md

@@ -0,0 +1,132 @@
+# Context Guardian
+
+A Claude Code **plugin** — four hooks + five skills + a shared library. Monitors context window usage via a real-time statusline and provides on-demand compaction tools.
+
+## Critical Rules
+
+### Versioning — bump ALL FOUR files or marketplace updates break:
+1. `package.json` → `"version"`
+2. `.claude-plugin/plugin.json` → `"version"`
+3. `.claude-plugin/marketplace.json` → `plugins[0].version`
+4. `README.md` → `[![Version]()`
+
+### Key Conventions
+- Session flags (`.claude/cg-*`) live in the **project's** `.claude/` dir, not plugin data — they're project-scoped and cleaned by SessionStart.
+- `.context-guardian/` at the project root holds user-visible artifacts (handoffs, checkpoint copies). Project-scoped, gitignored.
+- `${CLAUDE_PLUGIN_DATA}` (fallback `~/.claude/cg/`) holds plugin-internal state (config, session state, checkpoints, synthetic session manifest).
+- Skills invoke CLI entry points (`compact-cli.mjs`) via Bash because skills don't fire `UserPromptSubmit`.
+- Compaction and handoff automatically create synthetic JSONL sessions so `/resume cg` or `/resume cg:{label}` loads checkpoints as real conversation messages.
+
+## Statusline — Primary UX
+
+The statusline is CG's main communication channel. It shows real-time context usage and session size in the terminal status bar:
+
+```
+Context usage: 3% | Session size: 0.4/20MB | /cg:stats for more
+```
+
+**Two independent metrics, two independent color schemes:**
+
+| Metric | Green | Yellow | Red |
+|--------|-------|--------|-----|
+| Context usage | `pct < threshold × 0.7` | `pct < threshold` | `pct >= threshold` |
+| Session size | `< 10MB` | `10–15MB` | `>= 15MB` |
+
+- **Green/Yellow:** labels are dim/grey, only the numbers are colored
+- **Red:** entire label+number goes bold red for maximum visibility
+
+**Session size** is the estimated API request payload — transcript file size + system overhead (baseline_overhead × 4). This is separate from the token context window. The ~20MB API payload limit can lock users out entirely (can't send messages, can't even compact). The statusline warns before that happens.
+
+At threshold, the trailing hint changes to: `compaction recommended — /cg:compact`
+
+The session-start hook auto-configures the statusline and **reclaims it** if overwritten by another tool. The diagnostics check flags a missing CG statusline as a failure.
+
+## How The Submit Hook Works
+
+1. Every user message → submit hook reads real token counts from `message.usage` in the transcript JSONL. Falls back to byte estimation only on the very first message.
+2. Measures transcript file size (`fs.statSync`) as `payload_bytes` — proxy for the API request payload size.
+3. Writes token state + payload bytes to `state-{sessionId}.json` — consumed by `/cg:stats` and the statusline.
+4. Also writes state to the fixed fallback location (`~/.claude/cg/`) so the statusline can find it (the statusline process doesn't receive `CLAUDE_PLUGIN_DATA`).
+5. Handles manual compaction (`/cg:compact`, `/cg:prune`) via flag files or direct command detection.
+6. `/` messages bypass the hook entirely.
+
+No blocking, no menus, no cooldowns. The statusline handles all context pressure communication.
+
+## Compaction Design
+
+**Noise removal, not summarisation. Never lose context. No LLM involved — deterministic string processing.**
+
+### What stays (decision-relevant)
+- All user text (except affirmative confirmations like "yes", "ok")
+- All assistant reasoning text
+- Edit/Write diffs (start+end trim if >3K)
+- Bash commands + output (start+end trim if >5K)
+- AskUserQuestion answers, WebSearch results, Serena write tools, sequential thinking, agent results, all errors
+
+### What's removed (re-obtainable / noise)
+- File read results (Read/Grep/Glob) — dominant bloat, 30-50% of tokens
+- Thinking/redacted_thinking blocks
+- System/progress messages, Edit/Write success results
+- Serena read/query results, context-mode results, Serena memory results
+
+### Truncation
+Never chop at a point. Start+end trim: keep first N chars (intent) + last N chars (outcome), mark middle with `[...N chars trimmed from middle...]`.
+
+### Skip rules for user messages
+- Slash commands, CG menu replies (0-4, cancel), compact markers, affirmative confirmations, system injections → skip
+- "no", "n", bare numbers → KEEP (decisions)
+- Long structured user messages → KEEP regardless of size
+
+### Smart Compact vs Keep Recent
+- Smart Compact: all messages after last compaction boundary, with tiered compression and edit coalescing
+- Keep Recent: last 10 user exchanges (grouped with responses), same extraction engine
+
+## Session Handoff & Resume
+
+- `/cg:handoff [name]` → extracts conversation (same as Smart Compact), writes to `.context-guardian/cg-handoff-{slug}-{datetime}.md`
+- Both `/cg:compact` and `/cg:handoff` automatically create synthetic JSONL sessions in Claude Code's session directory
+- User restores via native `/resume cg:{hash}` (for compaction) or `/resume cg:{label}` (for handoff)
+- No custom resume skill — leverages Claude Code's built-in `/resume` which calls `setMessages()` to replace the conversation
+- The synthetic session contains the checkpoint as a real user message (not `additionalContext`), giving higher attention fidelity
+- A manifest (`synthetic-sessions.json` in plugin data dir) tracks one synthetic session per title, cleaning up the previous one on each write
+- Compaction checkpoints are also copied to `.context-guardian/cg-checkpoint-*.md` for user visibility
+- `rotateFiles` sorts by mtime (not filename) because label-prefixed filenames break alphabetical chronological ordering
+
+## Token Counting
+
+1. **Real counts (preferred):** `input_tokens + cache_creation_input_tokens + cache_read_input_tokens` from `message.usage` in transcript JSONL. Written by both submit and stop hooks.
+2. **Byte estimation (fallback):** First message only. Content bytes / 4.
+3. **Baseline overhead:** Stop hook captures on first response — irreducible floor (system prompts, tools, CLAUDE.md). Used in all savings estimates and session size calculation.
+
+## Session Size (API Payload Monitoring)
+
+The ~20MB API payload limit is **separate from the token context window**. When the raw request body exceeds ~20MB, the API rejects it entirely — you can't send messages, can't compact, can't do anything except `/clear`.
+
+Session size = `transcript file size` + `baseline_overhead × 4` (system overhead in bytes). This is tracked in `payload_bytes` in the state file, displayed in the statusline and `/cg:stats`, and shown as before/after in compaction results.
+
+The statusline reads session size from a fixed fallback location (`~/.claude/cg/state-*.json`) because the statusline process doesn't receive `CLAUDE_PLUGIN_DATA`. Both hooks write to this fallback in addition to the primary data dir.
+
+## Transcript JSONL Format
+
+Each line is JSON. Types: `user`, `assistant`, `system`, `progress`. User messages have `message.role === "user"` and `message.content` (string or array of text/tool_result/image/document blocks). Assistant messages have content arrays (text/tool_use/thinking blocks). Tool results link back via `tool_use_id`. The extraction engine uses a `Map<tool_use_id, {name, input}>` to classify results by originating tool.
+
+## Testing
+
+```bash
+bun test                        # all tests
+bun test test/handoff.test.mjs  # handoff/resume tests only
+tail -f ~/.claude/logs/cg.log   # watch hook activity
+```
+
+## Testing
+1. All tests must pass before recommending a push
+2. Code must remain above 80% code coverage on lines, functions, statements and branches
+3. Biome linting must pass before recommending a push
+
+## SonarQube Quality Gate
+
+1. Before recommending a push, run `sonar-scanner` using `source .env.local`.
+2. After scanning, use SonarQube MCP tools to check Quality Gate status. 
+3. If issues are flagged, fix holistically (not one rule at a time) and re-scan. Max 3 fix-scan cycles.
+4. If issues persist after 3 cycles, stop and report remaining issues with analysis.
+5. Only recommend pushing when the Quality Gate PASSES.   

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ricky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,362 @@
+# Context Guardian
+
+[![CI](https://github.com/Ricky-Stevens/context-guardian/actions/workflows/ci.yml/badge.svg)](https://github.com/Ricky-Stevens/context-guardian/actions/workflows/ci.yml)
+[![Version](https://img.shields.io/badge/version-2.1.0-blue)](https://github.com/Ricky-Stevens/context-guardian/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=Ricky-Stevens_context-guardian&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=Ricky-Stevens_context-guardian)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=Ricky-Stevens_context-guardian&metric=coverage)](https://sonarcloud.io/summary/new_code?id=Ricky-Stevens_context-guardian)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+
+**Automatic context window monitoring and smart compaction for Claude Code. Zero dependencies.**
+
+Context Guardian watches your context window usage in real time via a statusline and provides on-demand compaction tools. When usage crosses a configurable threshold, the statusline turns red and recommends compaction - preserving your work and keeping Claude sharp.
+
+Distributed as a **Claude Code plugin** - it's called "cg" due to how Claude Code namespaces skills. `/cg:stats` is easier to type than `/context-guardian:stats`.
+
+---
+
+## Install
+
+```bash
+/plugin marketplace add https://github.com/Ricky-Stevens/context-guardian
+/plugin install cg
+```
+
+**Note:** Claude's `/reload-plugins` can be a bit sketchy - try opening a new session if you hit issues.
+
+### Update
+
+To pull the latest version:
+
+1. Open `/plugins`
+2. Go to **Marketplaces** tab → select the context-guardian marketplace → **Update marketplace**
+3. Inside the marketplace, go to **Browse Plugins** → select cg → **Update**
+4. Run `/reload-plugins` or restart your session
+
+### Uninstall
+
+```bash
+/plugin uninstall cg
+```
+
+### Local development
+
+```bash
+claude --plugin-dir /path/to/cg
+```
+
+---
+
+## Commands
+
+Context Guardian adds five slash commands:
+
+### `/cg:stats`
+
+Shows current token usage, session size, compaction estimates, and recommendations.
+
+```
+┌─────────────────────────────────────────────────
+│  Context Guardian Stats
+│
+│  Current usage:   372,000 / 1,000,000 tokens (37.2%)
+│  Session size:    8.4MB / 20MB
+│  Threshold:       35% (0% remaining to warning)
+│  Data source:     real counts
+│
+│  Model:           claude-opus-4-6 / 1,000,000 tokens
+│  Last updated:    12 seconds ago
+│
+│  /cg:compact         ~37.2% → ~5%
+│  /cg:prune           ~37.2% → ~3%
+│
+│  /cg:handoff [name]  save session for later
+│
+└─────────────────────────────────────────────────
+```
+
+### `/cg:config`
+
+```bash
+/cg:config                     # show current config + auto-detected model/limit
+/cg:config threshold 0.50      # trigger at 50%
+/cg:config max_tokens 1000000  # override token limit
+/cg:config reset               # restore defaults
+```
+
+### `/cg:compact`
+
+Runs Smart Compact - a deterministic extraction engine that removes re-obtainable noise (file reads, grep results, thinking blocks, system messages) while preserving everything that matters: user messages, assistant reasoning, edit diffs, bash commands and output, user decisions, and errors. Typically achieves 70-90% reduction.
+
+After compaction, use `/resume cg:[4-char hash]` to restore the checkpoint.
+
+### `/cg:prune`
+
+Keeps the last 10 user exchanges (each grouped with their assistant responses and tool summaries). Uses the same extraction engine as Smart Compact. Good when only recent work matters.
+
+After pruning, use `/resume cg:[4-char hash]` to restore.
+
+### `/cg:handoff`
+
+Save your current session context for cross-session continuity. Uses the same extraction engine as Smart Compact.
+
+```bash
+/cg:handoff                    # save without a label
+/cg:handoff my auth refactor   # save with a custom name
+```
+
+Handoff files are saved to `.context-guardian/` in your project root. Add this directory to your `.gitignore`.
+
+To restore a handoff in a future session:
+
+```bash
+/resume cg:my-auth-refactor   # restore a specific handoff by label
+/resume                       # browse all sessions including CG handoffs
+```
+
+---
+
+## The Problem: Context Rot
+
+LLMs have a fixed context window - the total amount of text they can "see" at once. Claude Code sessions accumulate context rapidly: every message you send, every file Claude reads, every tool call and its output, every thinking block - it all stacks up.
+
+When the context window fills:
+
+- **The U-Shape.** Models perform best with information at the beginning or end of context. As the prompt grows, the middle gets less attention.
+- **Claude starts forgetting.** Earlier instructions, architectural decisions, and code context silently drop out of the effective attention window. Claude doesn't tell you it's forgotten - it just stops using that information.
+- **Quality degrades gradually.** You won't get an error. Responses become less coherent, less grounded in your codebase, and more likely to hallucinate.
+- **Native `/compact` is destructive.** When Claude Code hits ~95% usage, it summarizes everything into a brief paragraph, destroying the accumulated context.
+- **The 20MB wall.** Separately from the token limit, the API has a ~20MB request payload size limit. When your session's raw data exceeds this, the API rejects the request entirely — you can't send messages, can't compact, can't do anything except `/clear` and lose everything. Context Guardian tracks session size alongside token usage to warn you before you hit this hard wall.
+
+Context rot is insidious because **it's invisible**. You don't know Claude has forgotten something until the output is wrong.
+
+### Why This Matters More on Opus 4.6
+
+Opus 4.6 has a **1,000,000 token context window** - 5x larger than the previous 200K. This sounds like a pure advantage, but it creates a unique problem:
+
+- **Sessions last longer.** With 1M tokens, you can work for hours without hitting the limit. This means more accumulated context, more tool outputs, more file reads - and more opportunity for subtle quality degradation.
+- **The degradation is slower but deeper.** On Sonnet, you hit the wall at 200K and are forced to compact relatively quickly. On Opus, you can drift into the 40-60% range where quality is noticeably degraded but you haven't hit any hard limit.
+- **Cost scales with context.** Every API call sends the full context window. At 500K tokens, each message costs significantly more than at 50K. Compacting early saves money.
+- **Compaction quality depends on what's in context.** At 35%, Claude's full conversation is in sharp focus - it can produce a high-fidelity extraction. At 70%, earlier context is already fuzzy.
+
+The 1M window is powerful, but it requires active management. Context Guardian provides that management.
+
+---
+
+## Why 35%?
+
+Context Guardian triggers at **35% usage** by default. This is deliberately conservative.
+
+### The Sweet Spot for Model Recall
+
+[Research](https://news.mit.edu/2025/unpacking-large-language-model-bias-0617) on LLM attention patterns shows that models have a **U-shaped attention curve** - they attend strongly to the beginning and end of context, with weaker attention in the middle. As context grows:
+
+| Usage Range | Model Behavior |
+|-------------|---------------|
+| **0-25%** | Full attention across all content. Maximum recall and coherence. |
+| **25-40%** | Still strong. The "middle" is small enough that attention covers it well. |
+| **40-60%** | Noticeable degradation. Middle content gets less attention. Early instructions may be partially forgotten. |
+| **60-80%** | Significant degradation. Claude may contradict earlier decisions, forget constraints, or hallucinate details about code it read earlier. |
+| **80-95%** | Critical zone. Effective context is much smaller than the raw number suggests. |
+| **95%+** | Emergency auto-compact fires. Everything reduced to a brief summary. |
+
+**35% sits at the boundary between "full recall" and "beginning to degrade."** It's the last point where you can extract with full confidence that the output will be accurate, because Claude still has strong attention over the entire conversation.
+
+### What Actually Fills the Context
+
+In a typical Claude Code session, your actual conversation - what you typed and what Claude replied - is only **30-40% of total context**. The rest is:
+
+- **Tool outputs (40-50%):** File reads, grep results, command output. A single large file read can consume 10-20K tokens.
+- **System prompts (~5%):** CLAUDE.md, plugin instructions, skill descriptions, MCP server configs.
+- **Tool calls and thinking (10-15%):** The structured blocks that Claude generates internally.
+
+Smart Compact strips the re-obtainable noise and keeps the decision-relevant content. That's why it typically achieves **70-90% reduction** - most of the context is tool infrastructure, not your actual work.
+
+## How It Works
+
+### Compaction Engine
+
+Context Guardian uses a **deterministic string-processing engine** - no LLM is involved in extraction. It removes re-obtainable and disposable data while keeping all decision-relevant content at full fidelity.
+
+**What stays (decision-relevant):**
+- All user text messages (except affirmative confirmations like "yes", "ok")
+- All assistant reasoning text
+- Edit/Write diffs (start+end trimmed if >3K chars)
+- Bash commands and output (start+end trimmed if >5K chars)
+- User answers to questions (AskUserQuestion results)
+- Web search results, Serena write operations, sequential thinking chains
+- Agent results, all error responses
+
+**What's removed (re-obtainable / noise):**
+- File read results (Read, Grep, Glob) - the dominant bloat at 30-50% of tokens
+- Thinking and redacted_thinking blocks
+- System and progress messages
+- Edit/Write success confirmations (just "success")
+- Serena read/query results, context-mode results
+
+**Truncation:** When content exceeds its size limit, it's never chopped at a point. Start+end trim keeps the first N chars (intent) and last N chars (outcome), replacing only the middle with `[...N chars trimmed from middle...]`. This preserves the narrative thread because conclusions appear at the end.
+
+### Token Counting
+
+Context Guardian reads **actual token counts** from Claude Code's transcript. Every assistant message includes a `usage` object:
+
+```json
+{
+  "usage": {
+    "input_tokens": 3,
+    "cache_creation_input_tokens": 920,
+    "cache_read_input_tokens": 133868,
+    "output_tokens": 85
+  }
+}
+```
+
+**Context used = `input_tokens` + `cache_creation_input_tokens` + `cache_read_input_tokens`**
+
+These are the real values from the Anthropic API - the same numbers that determine your bill. On the first message of a session (before any assistant response exists), the plugin falls back to a byte-based estimate until real data is available.
+
+### How Restore Works
+
+After compaction or handoff, Context Guardian writes a **synthetic JSONL session** to Claude Code's session directory. This session contains the checkpoint as a real user message with a custom title (e.g., `cg` or `cg:my-feature`).
+
+When you type `/resume cg:{hash}`, Claude Code's native resume mechanism finds and loads this synthetic sessions, replacing the current conversation with the checkpoint content. Because it's a real user message (not injected context), the model gives it full attention.
+
+The flow:
+1. Run `/cg:compact`, `/cg:prune`, or `/cg:handoff [name]` - checkpoint saved + synthetic session created
+2. Type `/resume cg:{hash}` (or `/resume cg:{label}` for handoffs) - context restored
+
+---
+
+## Architecture
+
+### Hooks
+
+| Hook | Event | Purpose |
+|------|-------|---------|
+| `submit.mjs` | `UserPromptSubmit` | Writes token usage + payload size state for statusline and `/cg:stats` on every user message |
+| `session-start.mjs` | `SessionStart` | Cleans stale session flags, auto-configures statusline, self-healing marketplace clone |
+| `stop.mjs` | `Stop` | Writes fresh token state after each assistant response. Captures baseline overhead on first response. |
+| `precompact.mjs` | `PreCompact` | Injects CG's extraction as additional context into Claude Code's native `/compact` |
+
+### Skills
+
+Skills invoke `compact-cli.mjs` via Bash (since skills don't fire `UserPromptSubmit`). The CLI sets `CLAUDE_PLUGIN_DATA`, runs the extraction pipeline, and outputs JSON for the skill to display.
+
+| Skill | Entry Point |
+|-------|-------------|
+| `/cg:stats` | `lib/diagnostics.mjs` (health checks) + state file read |
+| `/cg:config` | Direct config file read/write |
+| `/cg:compact` | `lib/compact-cli.mjs smart` → `checkpoint.mjs:performCompaction()` |
+| `/cg:prune` | `lib/compact-cli.mjs recent` → `checkpoint.mjs:performCompaction()` |
+| `/cg:handoff` | `lib/compact-cli.mjs handoff` → `handoff.mjs:performHandoff()` |
+
+### Token Counting
+
+Two methods, preferring the more accurate. State is written by **both** the submit hook (before the response) and the stop hook (after the response), so `/cg:stats` always reflects the latest counts.
+
+1. **Real counts (preferred):** Reads `message.usage` from the most recent assistant message in the transcript JSONL. Calculates `input_tokens + cache_creation_input_tokens + cache_read_input_tokens`. Also detects the model name for auto-detecting max_tokens.
+
+2. **Byte estimation (fallback):** Only used on the very first message of a session (before any assistant response). Counts content bytes after the most recent compact marker and divides by 4.
+
+3. **Post-compaction estimates:** After compaction or checkpoint restore, a state file is written with estimated post-compaction token counts so `/cg:stats` works immediately.
+
+### Baseline Overhead
+
+On the first assistant response of each session, the stop hook captures the current token count as `baseline_overhead` - at that point, context is almost entirely system prompts, CLAUDE.md, and tool definitions. This measured value serves as an irreducible floor in all compaction savings estimates.
+
+### Statusline
+
+Context Guardian auto-configures a terminal statusline on first session start. It shows real-time context usage and session size:
+
+```
+Context usage: 3% | Session size: 0.4/20MB | /cg:stats for more
+```
+
+Two independent metrics with independent color schemes:
+
+| Metric | Green | Yellow | Red |
+|--------|-------|--------|-----|
+| Context usage | Well below threshold | Approaching threshold | At/past threshold |
+| Session size | < 10MB | 10–15MB | ≥ 15MB |
+
+In green/yellow states, labels are dim/grey with only the numbers colored. At red, the entire label+number goes bold red for maximum visibility.
+
+**Session size** tracks the estimated API request payload — transcript file size plus system overhead (prompts, tools, CLAUDE.md). The ~20MB API payload limit is separate from the token context window and can lock you out of a session entirely.
+
+The session-start hook **reclaims the statusline** if another tool overwrites it, logging a warning and notifying the user via `additionalContext`.
+
+### Model & Token Limit Auto-Detection
+
+Every assistant message in the transcript includes a `model` field (e.g., `"claude-opus-4-6"`). Context Guardian uses this to set the token limit:
+
+- **Opus 4.6+** (major >= 4, minor >= 6): **1,000,000 tokens**
+- **Everything else** (Sonnet, Haiku, older Opus): **200,000 tokens**
+
+This is imperfect - I haven't found a better way to do this yet. Contributions or ideas welcome.
+
+You can override this with `/cg:config max_tokens <value>` if the auto-detection doesn't match your setup.
+
+### Data Storage
+
+All persistent data lives in the plugin's data directory (`${CLAUDE_PLUGIN_DATA}`, typically `~/.claude/plugins/data/cg/`):
+
+| File | Purpose |
+|------|---------|
+| `config.json` | Threshold and max_tokens override |
+| `state-{session_id}.json` | Latest token counts, payload bytes, model, transcript path (session-scoped) |
+| `checkpoints/` | Saved compaction checkpoints (markdown) |
+| `synthetic-sessions.json` | Manifest tracking synthetic JSONL sessions for `/resume` |
+
+Each project also has a `.context-guardian/` directory at its root:
+
+| File | Purpose |
+|------|---------|
+| `cg-handoff-[name]-{datetime}.md` | Session handoff files (from `/cg:handoff`) |
+| `cg-checkpoint-{datetime}.md` | Copies of compaction checkpoints for visibility |
+
+These files are project-scoped - each project gets its own isolated set. Add `.context-guardian/` to your `.gitignore`.
+
+---
+
+## Logging
+
+All hook activity logs to `~/.claude/logs/cg.log`:
+
+```bash
+tail -f ~/.claude/logs/cg.log
+```
+
+Log entries include token counts, threshold checks, checkpoint creation with compression stats, synthetic session writes, and handoff activity.
+
+---
+
+## Troubleshooting
+
+**Token counts show "estimated":**
+- Only happens on the first message of a session. After one exchange, counts become real.
+
+**`/resume cg` doesn't find the session:**
+- Ensure you ran `/cg:compact`, `/cg:prune`, or `/cg:handoff` first - these create the synthetic session.
+- Check logs: `tail -20 ~/.claude/logs/cg.log`
+
+**Plugin not loading:**
+- Check logs: `tail -20 ~/.claude/logs/cg.log`
+- Verify plugin is loaded: `/plugins`
+- Try: `/plugin uninstall cg` then `/plugin install cg`
+
+---
+
+## Contributing
+
+```bash
+bun test              # run all tests (604 across 24 files)
+npx biome check       # lint
+```
+
+The e2e test (`test/compaction-e2e.test.mjs`) creates a 26-turn coding session with 19 trackable facts and 5 noise items, verifying every fact survives extraction and all noise is removed. If any change drops a fact, the test names exactly which one was lost.
+
+---
+
+## License
+
+MIT