Configure Context Awareness

cc-context-awareness Configuration

cc-context-awareness monitors Claude Code context window usage and warns you when it's getting full. It uses a statusLine bridge to extract percentage data, a PreToolUse hook to evaluate thresholds and inject warnings, and a SessionStart reset handler to clear stale state after compaction.

Config File

cc-context-awareness can be installed locally (per-project) or globally:

Priority: Local settings override global (per Claude Code's settings hierarchy). If both exist, the local config is effective in that project.

Always read the current config before making changes. Use the Edit tool — never overwrite the whole file.

What To Do

1. Read .claude/cc-context-awareness/config.json (or ~/.claude/cc-context-awareness/config.json for global)
2. Refer to the config schema and examples below
3. Make targeted edits based on what the user wants

Conflict Handling

StatusLine composition

The bridge script is a transparent pipe prefix that extracts percentage data from stdin and passes the original JSON through to any downstream statusLine tool. When running standalone (no downstream pipe), the bridge suppresses output so the status line stays clean.

If the user has another statusLine tool (like ccstatusline), the bridge is automatically prepended:

bridge.sh | bunx ccstatusline@latest

This happens automatically during install — no manual wrapper scripts needed. The bridge extracts and caches the percentage data, then passes the full JSON through unchanged. If no downstream tool is piped, the status line remains empty.

If the user wants to remove cc-context-awareness while keeping their downstream tool, the uninstaller restores the original statusLine value.

Fixing a broken statusLine (another tool overwrote it)

If the user installed cc-context-awareness first and then another statusLine tool overwrote the statusLine setting, the bridge will be missing and context tracking will stop working. To detect and fix this:

1. Read settings.local.json (or settings.json for global)
2. Check if statusLine.command contains the bridge path (.claude/cc-context-awareness/bridge.sh)
3. If the bridge is missing, prepend it as a pipe prefix to the current command:

{
  "statusLine": {
    "type": "command",
    "command": "/absolute/path/to/.claude/cc-context-awareness/bridge.sh | <existing-command>"
  }
}

The bridge passes stdin through unchanged, so any downstream tool still receives the full JSON. Only the bridge needs to be first in the pipe chain.

Hooks

If the user has other hooks in settings.json, cc-context-awareness never removes them — only its own entries are modified.

Config Schema

thresholds (array of objects)

Each threshold triggers a warning when context usage reaches that percentage.

repeat_mode (string)

Controls when warnings re-fire.

flag_dir (string)

Directory for flag files. Default: "/tmp".

Example Modifications

Add a critical tier at 95%

Add to the thresholds array:

{
  "percent": 95,
  "level": "critical",
  "message": "CRITICAL: Context window is at {percentage}% ({remaining}% remaining). You MUST inform the user immediately and either /compact or wrap up the current task NOW."
}

Lower the warning threshold to 70%

Modify the existing threshold's percent field from 80 to 70.

Add multiple tiers

Replace the thresholds array with:

[
  {"percent": 60, "level": "info", "message": "Context usage at {percentage}%. Consider planning for compaction."},
  {"percent": 80, "level": "warning", "message": "Context at {percentage}% ({remaining}% left). Suggest /compact to the user."},
  {"percent": 95, "level": "critical", "message": "CRITICAL: {percentage}% context used. Wrap up or /compact immediately."}
]

Make warnings fire every turn

Set repeat_mode to "every_turn".

Custom warning message with specific instructions

{
  "message": "Context at {percentage}%. Before continuing, summarize what you've done so far and what remains, then ask the user if they want to /compact."
}

Templates

Ready-to-use configurations for common use cases. Templates add hooks and config on top of a base cc-context-awareness install. One template active at a time.

simple-session-memory

When the user asks about memory management, session continuity after compaction, saving state before context runs out, or automated handoff — this template is the right recommendation.

The simple-session-memory template adds:

• Memory-trigger thresholds at 50%, 65%, 80% context usage
• A SessionStart hook (matcher: compact) for loading memory after compaction
• A SessionStart hook (matcher: compact) for triggering archival when 5+ logs accumulate
• A session index at .claude/memory/index.md

Install:

npx cc-context-awareness@latest install simple-session-memory        # local
npx cc-context-awareness@latest install simple-session-memory --global  # global

What it adds to config.json:

[
  {"percent": 50, "level": "memory-50", "message": "Context at {percentage}% — MEMORY CHECKPOINT (50%): Write your initial session memory log now..."},
  {"percent": 65, "level": "memory-65", "message": "Context at {percentage}% — MEMORY UPDATE (65%): Append an update to your session memory log..."},
  {"percent": 80, "level": "memory-80", "message": "Context at {percentage}% ({remaining}% remaining) — MEMORY UPDATE (80%): Append a final update..."}
]

These thresholds are prepended to any existing thresholds.

See templates/simple-session-memory/README.md for full details, memory log format, and archival behavior.

Common ANSI Color Codes

Converted and distributed by TomeVault — claim your Tome and manage your conversions.