/clear-context

name: clear-context
description: Manages context overflow by handing off to a fresh subagent at 80% usage. Use when context pressure is critical and work must continue uninterrupted.
alwaysApply: false
category: conservation
token_budget: 200
progressive_loading: true
hooks:
  PreToolUse:
  - matcher: Task
    command: 'echo "[skill:clear-context] Subagent delegation at $(date)" >> ${CLAUDE_CODE_TMPDIR:-/tmp}/clear-context-audit.log

      '
model_hint: standard
role: library

Table of Contents

• [Quick Start](#quick-start)
• [When to Use](#when-to-use)
• [The Auto-Clear Pattern](#the-auto-clear-pattern)
• [Thresholds](#thresholds)
• [Auto-Clear Workflow](#auto-clear-workflow)
• [Integration with Existing Hooks](#integration-with-existing-hooks)
• [Self-Monitoring Pattern](#self-monitoring-pattern)

Clear Context Skill

Quick Start

When context pressure reaches critical levels (80%+), invoke this skill to: 1. Save current session state 2. Delegate continuation to a fresh subagent 3. Continue work without manual intervention

Skill(conserve:clear-context)

When To Use

• **Proactively**: Before starting large multi-chained tasks
• **Reactively**: When context warning indicates 80%+ usage
• **Automatically**: Integrated into long-running workflows

When NOT To Use

• Context usage is under 50% - continue working normally
• Mid-critical-operation where handoff would lose state
• **Consider "Summarize from here" first** (Claude Code 2.1.32+): Before full auto-clear,

try partial summarization via the message selector. This compresses older context while preserving recent work, often sufficient to relieve pressure without a full handoff.

The Auto-Clear Pattern

Since `/clear` requires user action, we achieve automatic context clearing without interruption through **subagent delegation**:

Main Agent (high context)
    ↓
    Saves state to .claude/session-state.md
    ↓
    Spawns continuation subagent (fresh context)
    ↓
    Subagent reads state, continues work

Thresholds

| Level | Threshold | Action | |-------|-----------|--------| | WARNING | 40% | Monitor, plan optimization | | CRITICAL | 50% | Prepare for handoff | | EMERGENCY | 80% | **Execute auto-clear now** |

**Configuration** (environment variables):

• `CONSERVE_EMERGENCY_THRESHOLD`: Override 80% default (e.g., `0.75` for 75%)
• `CONSERVE_SESSION_STATE_PATH`: Override `.claude/session-state.md` default

Auto-Clear Workflow

Step 1: Assess Current State

Before triggering auto-clear, gather:

• Current task/goal description
• Progress made so far
• Key decisions and rationale
• Files being actively worked on
• Open TodoWrite items

Step 1.5: Finalize Task List Before Handoff

**Important**: Before saving state or spawning a continuation agent, reconcile the task list:

1. **Review all tasks** via `TaskList` 2. **Mark completed tasks** as `completed` via `TaskUpdate`: do NOT leave done work as `in_progress` 3. **Record existing task IDs**: collect all task IDs (pending and in_progress) to pass in the session state so the continuation agent references them instead of creating duplicates 4. **Include task IDs in session state** under the `existing_task_ids` field (see Step 2)

This prevents the continuation agent from creating duplicate tasks.

Step 2: Save Session State

**Important**: If `.claude/session-state.md` already exists, always Read it first before writing (Claude Code requires reading existing files before overwriting). Create the `.claude/` directory if it doesn't exist.

Write to `.claude/session-state.md` (or `$CONSERVE_SESSION_STATE_PATH`):

# Session State Checkpoint
state_version: 1
Generated: [timestamp]
Reason: Context threshold exceeded (80%+)

## Execution Mode

**Mode**: [unattended | interactive | dangerous]
**Auto-Continue**: [true | false]
**Source Command**: [do-issue | execute-plan | etc.]
**Remaining Tasks**: [list of pending items]

> **Important**: If `auto_continue: true` or mode is `dangerous`/`unattended`,
> the continuation agent should not pause for user confirmation.
> Continue executing all remaining tasks until completion.

## Current Task
[What we're trying to accomplish]

## Progress Summary
[What's been done so far]

## Key Decisions
- Decision 1: [rationale]
- Decision 2: [rationale]

## Active Files
- path/to/file1.py - [status]
- path/to/file2.md - [status]

## Pending TodoWrite Items
- [ ] Item 1
- [ ] Item 2

## Existing Task IDs
[List task IDs from TaskList so the continuation agent can reference them
instead of creating duplicates. Example:]
- Task #1: "Implement feature X" (in_progress)
- Task #2: "Write tests for feature X" (pending)

## Continuation Instructions
[Specific next steps for the continuation agent]

**Execution Mode Detection**:

Before writing state, detect the execution mode:

# Detect execution mode from environment/context
execution_mode = {
    "mode": "interactive",  # default
    "auto_continue": False,
    "source_command": None,
    "remaining_tasks": [],
    "dangerous_mode": False,
}

# Check for dangerous/unattended mode indicators
if os.environ.get("CLAUDE_DANGEROUS_MODE") == "1":
    execution_mode["mode"] = "dangerous"
    execution_mode["auto_continue"] = True
    execution_mode["dangerous_mode"] = True
elif os.environ.get("CLAUDE_UNATTENDED") == "1":
    execution_mode["mode"] = "unattended"
    execution_mode["auto_continue"] = True

# Inherit from parent session state if exists
if parent_state and parent_state.get("execution_mode"):
    execution_mode = parent_state["execution_mode"]

Step 2.5: Verify Session-State Clarity Before Handoff

A continuation agent inherits only what `session-state.md` says. If the draft is ambiguous, the new agent starts from corrupted task state. Before spawning, gate the handoff on the belief-clarity check (the `belief-clarity` module of `Skill(conserve:context-optimization)`), which asks two anchor questions against the draf