cc-context-awareness Configuration

cc-context-awareness monitors Claude Code context window usage and warns you when it's getting full. It uses a status line to show usage, a hook to inject warnings into the conversation, and a 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
2. •Refer to the config schema and examples below
3. •Make targeted edits based on what the user wants

Conflict Handling

StatusLine conflicts

If another tool (e.g. ccstatusline) is using the statusLine slot, cc-context-awareness can wrap or merge with it instead of replacing it. The statusline script writes a flag file that the hook reads — this bridge must be preserved.

Option 1: Wrap (recommended)

Create a wrapper script that calls both statuslines:

#!/usr/bin/env bash
# ~/.claude/statusline-wrapper.sh
INPUT=$(cat)
echo "$INPUT" | /path/to/other/statusline.sh
echo "$INPUT" | ~/.claude/cc-context-awareness/context-awareness-statusline.sh

Then update settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline-wrapper.sh"
  }
}

Option 2: Merge

Copy the flag-writing logic from ~/.claude/cc-context-awareness/context-awareness-statusline.sh into the existing statusline script. The critical parts are:

1. •Reading thresholds from ~/.claude/cc-context-awareness/config.json
2. •Writing the trigger file to /tmp/.cc-ctx-trigger-{session_id} when thresholds are crossed
3. •Tracking fired tiers in /tmp/.cc-ctx-fired-{session_id}
4. •Clearing both files on compaction via the SessionStart reset handler

The hook reads from the trigger file, so as long as that file is written correctly, warnings will fire.

Other conflicts

• •If the user has other hooks in settings.json, never remove them — only modify cc-context-awareness entries
• •If editing thresholds, ensure each level value is unique

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.

statusline (object)

Controls the status bar appearance.

hook_event (string)

Which Claude Code hook event triggers the context injection.

Changing this value also requires re-running the installer to update settings.json:

./install.sh --hook-event PostToolUse

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."}
]

Change bar style to simple ASCII

{
  "bar_filled": "#",
  "bar_empty": "-"
}

Use yellow for warnings instead of red

Set color_warning to "33" (ANSI yellow).

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."
}

Common ANSI Color Codes